Class: Shojiku::Result

Inherits:
Object
  • Object
show all
Defined in:
lib/shojiku/result.rb

Overview

What every lifecycle operation returns.

Nothing in the normal flow raises. A template that will not render, a key that will not sign, a signature that does not verify are all data you query — success?, the value, the engine's diagnostics either way, and on failure the Failure trace.

Diagnostics ride on a SUCCESS too. A render that worked can still have warned about an overflowing box, and a caller that only looks at failures never sees them.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(value: nil, diagnostics: [], failure: nil) ⇒ Result

Returns a new instance of Result.



25
26
27
28
29
 
# File 'lib/shojiku/result.rb', line 25

def initialize(value: nil, diagnostics: [], failure: nil)
  @value = value
  @diagnostics = diagnostics
  @failure = failure
end

Instance Attribute Details

#diagnostics ⇒ Object (readonly)

Returns the value of attribute diagnostics.



15
16
17
 
# File 'lib/shojiku/result.rb', line 15

def diagnostics
  @diagnostics
end

#failure ⇒ Object (readonly)

Returns the value of attribute failure.



15
16
17
 
# File 'lib/shojiku/result.rb', line 15

def failure
  @failure
end

#value ⇒ Object (readonly) Also known as: artifact, report

Returns the value of attribute value.



15
16
17
 
# File 'lib/shojiku/result.rb', line 15

def value
  @value
end

Class Method Details

.failed(failure) ⇒ Object 



21
22
23
 
# File 'lib/shojiku/result.rb', line 21

def self.failed(failure)
  new(failure: failure, diagnostics: failure.diagnostics)
end

.succeeded(value, diagnostics) ⇒ Object 



17
18
19
 
# File 'lib/shojiku/result.rb', line 17

def self.succeeded(value, diagnostics)
  new(value: value, diagnostics: diagnostics)
end

Instance Method Details

#errors ⇒ Object

Only the diagnostics that are errors — the ones that explain a refusal.



66
67
68
 
# File 'lib/shojiku/result.rb', line 66

def errors
  @diagnostics.select(&:error?)
end

#failure? ⇒ Boolean

Returns:

  • (Boolean) 


35
36
37
 
# File 'lib/shojiku/result.rb', line 35

def failure?
  !success?
end

#success? ⇒ Boolean

Returns:

  • (Boolean) 


31
32
33
 
# File 'lib/shojiku/result.rb', line 31

def success?
  @failure.nil?
end

#value! ⇒ Object Also known as: artifact!, report!

The value, or a raised UnwrapError when the operation failed.

The opt-in bridge for a script that wants a stack trace rather than a branch, and the ONE place this API raises for something other than a misused argument. That is why the ruling is stated rather than implied, and frozen for every Shojiku SDK: calling unwrap on a failed result is programmer misuse — a caller who has not checked success? is asserting the operation worked. Application code that handles failure keeps using success? and #failure; nothing in this gem calls these.

(Go is the recorded exception: the language has no exceptions, so its SDK mirrors the shape as an error return rather than a panic.)

Raises:



56
57
58
59
60
 
# File 'lib/shojiku/result.rb', line 56

def value!
  raise UnwrapError, @failure if @failure

  @value
end

#warnings ⇒ Object

Only the warnings, which a SUCCESSFUL result can carry.



71
72
73
 
# File 'lib/shojiku/result.rb', line 71

def warnings
  @diagnostics.select(&:warning?)
end