Class: MonadOxide::Ok

Inherits:
Result
  • Object
show all
Defined in:
lib/ok.rb

Overview

‘Ok’ represents a success ‘Result’. For most operations, ‘Ok’ will perform some operation. Exceptions raised during calls to ‘Ok’ will coerce the chain into ‘Err’, which generally causes execution to fall through the entire chain.

Instance Method Summary collapse

Methods inherited from Result

#flatten, #match, try

Constructor Details

#initialize(data) ⇒ Ok

Constructs an ‘Ok’ with the data provided.

Parameters:

  • data (Object) —

    The inner data this Result encapsulates.



14
15
16
 
# File 'lib/ok.rb', line 14

def initialize(data)
  @data = data
end

Instance Method Details

#and_then(f = nil) { ... } ⇒ Ok<B> | Err<C>

Invokes ‘f’ or the block with the data and returns the Result returned from that. Exceptions raised during ‘f’ or the block will return an ‘Err<Exception>’. The return type is enforced.

Parameters:

  • f (Proc<A, Result<B>>) (defaults to: nil) —

    The function to call. Could be a block instead. Takes an [A=Object] and must return a [Result<B>].

Yields:

  • Will yield a block that takes an A and returns a Result<B>. Same as ‘f’ parameter.

Returns:

  • (Ok<B> | Err<C>) —

    A new Result from ‘f’ or the block. Exceptions raised will result in ‘Err<C>’. If ‘f’ returns a non-Result, this will return ‘Err<ResultReturnExpectedError>’.



29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/ok.rb', line 29

def and_then(f=nil, &block)
  begin
    r = (f || block).call(@data)
    # Enforce that we always get a Result. Without a Result, coerce to an
    # Err.
    if !r.kind_of?(Result)
      raise ResultReturnExpectedError.new(r)
    else
      r
    end
  rescue => e
    Err.new(e)
  end
end

#err? ⇒ Boolean

Identifies that this is not an ‘Err`. For counterparts:

Returns:

  • (Boolean) —

    ‘false` because this is not an `Err`.

See Also:



51
52
53
 
# File 'lib/ok.rb', line 51

def err?()
  false
end

#inspect_err(f = nil) { ... } ⇒ Ok

Falls through. @see Result#inspect_err for how this is handled in either Result case, and @see Err#inspect_err for how this is handled in the Err case.

Parameters:

  • f (Proc) (defaults to: nil) —

    Optional Proc - ignored.

Yields:

  • An ignored block.

Returns:

  • (Ok) —

    This Ok.



62
63
64
 
# File 'lib/ok.rb', line 62

def inspect_err(f=nil, &block)
  self
end

#inspect_ok(f = nil) { ... } ⇒ Result<A>

Applies ‘f’ or the block over the data and returns the same ‘Ok’. No changes are applied. This is ideal for logging. Exceptions raised during these transformations will return an ‘Err’ with the Exception.

Parameters:

  • f (Proc<A, B>) (defaults to: nil) —

    The function to call. Could be a block instead. Takes an [A] the return is ignored.

Yields:

  • Will yield a block that takes an A the return is ignored. Same as ‘f’ parameter.

Returns:

  • (Result<A>) —

    returns self.



75
76
77
78
79
80
81
82
 
# File 'lib/ok.rb', line 75

def inspect_ok(f=nil, &block)
  begin
    (f || block).call(@data)
    self
  rescue => e
    Err.new(e)
  end
end

#map(f = nil) { ... } ⇒ Result<B>

Applies ‘f’ or the block over the data and returns a new ‘Ok’ with the returned value.

Parameters:

  • f (Proc<A, B>) (defaults to: nil) —

    The function to call. Could be a block instead. Takes an [A=Object] and returns a B.

Yields:

  • Will yield a block that takes an A and returns a B. Same as ‘f’ parameter.

Returns:

  • (Result<B>) —

    A new ‘Ok<B>’ whose ‘B’ is the return of ‘f’ or the block. Errors raised when applying ‘f’ or the block will result in a returned ‘Err<Exception>’.



94
95
96
97
98
99
100
 
# File 'lib/ok.rb', line 94

def map(f=nil, &block)
  begin
    self.class.new((f || block).call(@data))
  rescue => e
    Err.new(e)
  end
end

#map_err(f = nil) { ... } ⇒ Result<A>

This is a no-op for Ok. @see Err#map_err.

Parameters:

  • f (Proc<A, B>) (defaults to: nil) —

    A dummy function. Not used.

Yields:

  • A dummy block. Not used.

Returns:

  • (Result<A>) —

    This ‘Ok’.



107
108
109
 
# File 'lib/ok.rb', line 107

def map_err(f=nil, &block)
  self
end

#ok? ⇒ Boolean

Identifies that this is an ‘Ok`. For counterparts:

Returns:

  • (Boolean) —

    ‘true` because this is an `Ok`.

See Also:



118
119
120
 
# File 'lib/ok.rb', line 118

def ok?()
  true
end

#or_else(f = nil) { ... } ⇒ Result<A>

The Err equivalent to Ok#and_then. This is a no-op for Ok. @see Err#or_else.

Parameters:

  • f (Proc<A, B>) (defaults to: nil) —

    A dummy function. Not used.

Yields:

  • A dummy block. Not used.

Returns:

  • (Result<A>) —

    This ‘Ok’.



128
129
130
 
# File 'lib/ok.rb', line 128

def or_else(f=nil, &block)
  self
end

#unwrap ⇒ A

Dangerously access the ‘Ok’ data. If this is an ‘Err’, an exception will be raised. It is recommended to use this for tests only.

Returns:

  • (A) —

    The inner data of this ‘Ok’.



136
137
138
 
# File 'lib/ok.rb', line 136

def unwrap()
  @data
end

#unwrap_err ⇒ E

Dangerously access the ‘Err’ data. If this is an ‘Ok’, an exception will be raised. It is recommended to use this for tests only.

Returns:

  • (E) —

    The ‘Exception’ of this ‘Err’.

Raises:



144
145
146
147
148
 
# File 'lib/ok.rb', line 144

def unwrap_err()
  raise UnwrapError.new(
    "#{self.class} with #{@data.inspect} could not be unwrapped as an Err.",
  )
end

#unwrap_err_or_else(f = nil) { ... } ⇒ B

Safely unwrap the ‘Result`. In the case of `Ok`, this uses the provided function to produce a value.

Parameters:

  • f (Proc<B>) (defaults to: nil) —

    The function to call. Could be a block instead. Takes nothing and returns a [B=Object].

Yields:

  • Will yield a block that takes nothing and returns a [B=Object]. Same as ‘f’ parameter.

Returns:

  • (B) —

    The value returned from ‘f`.



159
160
161
 
# File 'lib/ok.rb', line 159

def unwrap_err_or_else(f=nil, &block)
  (f || block).call()
end

#unwrap_or(_x) ⇒ A

Safely unwrap the ‘Result`. In the case of `Ok`, this returns the data in the Ok.

Parameters:

  • _x (B) —

    The value that will be returned.

Returns:

  • (A) —

    The data in the Ok.



169
170
171
 
# File 'lib/ok.rb', line 169

def unwrap_or(_x)
  @data
end

#unwrap_or_else(_f = nil, &_block) ⇒ B

Safely unwrap the ‘Result`. In the case of `Ok`, this returns the wrapped value.

Parameters:

  • f (Proc<B>) —

    A dummy function. Not used. instead. Takes nothing and returns a [B=Object].

Returns:

  • (B) —

    The value returned from ‘f`.



180
181
182
 
# File 'lib/ok.rb', line 180

def unwrap_or_else(_f=nil, &_block)
  @data
end