Class: Concurrent::Maybe
- Inherits:
-
Synchronization::Object
- Object
- Synchronization::Object
- Concurrent::Maybe
- Includes:
- Comparable
- Defined in:
- lib/concurrent-ruby/concurrent/maybe.rb
Overview
A Maybe
encapsulates an optional value. A Maybe
either contains a value
of (represented as Just
), or it is empty (represented as Nothing
). Using
Maybe
is a good way to deal with errors or exceptional cases without
resorting to drastic measures such as exceptions.
Maybe
is a replacement for the use of nil
with better type checking.
For compatibility with Concern::Obligation the predicate and
accessor methods are aliased as fulfilled?
, rejected?
, value
, and
reason
.
Motivation
A common pattern in languages with pattern matching, such as Erlang and Haskell, is to return either a value or an error from a function Consider this Erlang code:
case file:consult("data.dat") of
{ok, Terms} -> do_something_useful(Terms);
{error, Reason} -> lager:error(Reason)
end.
In this example the standard library function file:consult
returns a
tuple
with two elements: an atom
(similar to a ruby symbol) and a variable containing ancillary data. On
success it returns the atom ok
and the data from the file. On failure it
returns error
and a string with an explanation of the problem. With this
pattern there is no ambiguity regarding success or failure. If the file is
empty the return value cannot be misinterpreted as an error. And when an
error occurs the return value provides useful information.
In Ruby we tend to return nil
when an error occurs or else we raise an
exception. Both of these idioms are problematic. Returning nil
is
ambiguous because nil
may also be a valid value. It also lacks
information pertaining to the nature of the error. Raising an exception
is both expensive and usurps the normal flow of control. All of these
problems can be solved with the use of a Maybe
.
A Maybe
is unambiguous with regard to whether or not it contains a value.
When Just
it contains a value, when Nothing
it does not. When Just
the value it contains may be nil
, which is perfectly valid. When
Nothing
the reason for the lack of a value is contained as well. The
previous Erlang example can be duplicated in Ruby in a principled way by
having functions return Maybe
objects:
result = MyFileUtils.consult("data.dat") # returns a Maybe
if result.just?
do_something_useful(result.value) # or result.just
else
logger.error(result.reason) # or result.nothing
end
Constant Summary collapse
- NONE =
::Object.new.freeze
Instance Attribute Summary collapse
-
#just ⇒ undocumented
(also: #value)
readonly
The value of a
Maybe
whenJust
. -
#nothing ⇒ undocumented
(also: #reason)
readonly
The reason for the
Maybe
whenNothing
.
Class Method Summary collapse
-
.from(*args) {|args| ... } ⇒ Maybe
Create a new
Maybe
using the given block. -
.just(value) ⇒ Maybe
Create a new
Just
with the given value. -
.nothing(error = '') ⇒ Maybe
Create a new
Nothing
with the given (optional) reason.
Instance Method Summary collapse
-
#<=>(other) ⇒ Integer
Comparison operator.
-
#just? ⇒ Boolean
(also: #fulfilled?)
Is this
Maybe
aJust
(successfully fulfilled with a value)?. -
#nothing? ⇒ Boolean
(also: #rejected?)
Is this
Maybe
anothing
(rejected with an exception upon fulfillment)?. -
#or(other) ⇒ Object
Return either the value of self or the given default value.
Instance Attribute Details
#just ⇒ undocumented (readonly) Also known as: value
The value of a Maybe
when Just
. Will be NONE
when Nothing
.
114 115 116 |
# File 'lib/concurrent-ruby/concurrent/maybe.rb', line 114 def just @just end |
#nothing ⇒ undocumented (readonly) Also known as: reason
The reason for the Maybe
when Nothing
. Will be NONE
when Just
.
117 118 119 |
# File 'lib/concurrent-ruby/concurrent/maybe.rb', line 117 def nothing @nothing end |
Class Method Details
.from(*args) {|args| ... } ⇒ Maybe
Create a new Maybe
using the given block.
Runs the given block passing all function arguments to the block as block
arguments. If the block runs to completion without raising an exception
a new Just
is created with the value set to the return value of the
block. If the block raises an exception a new Nothing
is created with
the reason being set to the raised exception.
137 138 139 140 141 142 143 144 145 |
# File 'lib/concurrent-ruby/concurrent/maybe.rb', line 137 def self.from(*args) raise ArgumentError.new('no block given') unless block_given? begin value = yield(*args) return new(value, NONE) rescue => ex return new(NONE, ex) end end |
.just(value) ⇒ Maybe
Create a new Just
with the given value.
152 153 154 |
# File 'lib/concurrent-ruby/concurrent/maybe.rb', line 152 def self.just(value) return new(value, NONE) end |
.nothing(error = '') ⇒ Maybe
Create a new Nothing
with the given (optional) reason.
164 165 166 167 168 169 170 171 |
# File 'lib/concurrent-ruby/concurrent/maybe.rb', line 164 def self.nothing(error = '') if error.is_a?(Exception) nothing = error else nothing = StandardError.new(error.to_s) end return new(NONE, nothing) end |
Instance Method Details
#<=>(other) ⇒ Integer
Comparison operator.
199 200 201 202 203 204 205 |
# File 'lib/concurrent-ruby/concurrent/maybe.rb', line 199 def <=>(other) if nothing? other.nothing? ? 0 : -1 else other.nothing? ? 1 : just <=> other.just end end |
#just? ⇒ Boolean Also known as: fulfilled?
Is this Maybe
a Just
(successfully fulfilled with a value)?
176 177 178 |
# File 'lib/concurrent-ruby/concurrent/maybe.rb', line 176 def just? ! nothing? end |
#nothing? ⇒ Boolean Also known as: rejected?
Is this Maybe
a nothing
(rejected with an exception upon fulfillment)?
184 185 186 |
# File 'lib/concurrent-ruby/concurrent/maybe.rb', line 184 def nothing? @nothing != NONE end |
#or(other) ⇒ Object
Return either the value of self or the given default value.
210 211 212 |
# File 'lib/concurrent-ruby/concurrent/maybe.rb', line 210 def or(other) just? ? just : other end |