Class: Concurrent::Maybe
- Inherits:
-
Synchronization::Object
- Object
- Synchronization::Object
- Concurrent::Maybe
- Includes:
- Comparable
- Defined in:
- lib/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
- NONE =
Object.new.freeze
Instance Attribute Summary (collapse)
-
- (undocumented) just
(also: #value)
readonly
The value of a
MaybewhenJust. -
- (undocumented) nothing
(also: #reason)
readonly
The reason for the
MaybewhenNothing.
Class Method Summary (collapse)
-
+ (Maybe) from(*args) {|args| ... }
Create a new
Maybeusing the given block. -
+ (Maybe) just(value)
Create a new
Justwith the given value. -
+ (Maybe) nothing(error = '')
Create a new
Nothingwith the given (optional) reason.
Instance Method Summary (collapse)
-
- (Integer) <=>(other)
Comparison operator.
-
- (Boolean) just?
(also: #fulfilled?)
Is this
MaybeaJust(successfully fulfilled with a value)?. -
- (Boolean) nothing?
(also: #rejected?)
Is this
Maybeanothing(rejected with an exception upon fulfillment)?. -
- (Object) or(other)
Return either the value of self or the given default value.
Instance Attribute Details
- (undocumented) just (readonly) Also known as: value
The value of a Maybe when Just. Will be NONE when Nothing.
114 115 116 |
# File 'lib/concurrent/maybe.rb', line 114 def just @just end |
- (undocumented) nothing (readonly) Also known as: reason
The reason for the Maybe when Nothing. Will be NONE when Just.
117 118 119 |
# File 'lib/concurrent/maybe.rb', line 117 def nothing @nothing end |
Class Method Details
+ (Maybe) from(*args) {|args| ... }
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/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 |
+ (Maybe) just(value)
Create a new Just with the given value.
152 153 154 |
# File 'lib/concurrent/maybe.rb', line 152 def self.just(value) return new(value, NONE) end |
+ (Maybe) nothing(error = '')
Create a new Nothing with the given (optional) reason.
164 165 166 167 168 169 170 171 |
# File 'lib/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
- (Integer) <=>(other)
Comparison operator.
199 200 201 202 203 204 205 |
# File 'lib/concurrent/maybe.rb', line 199 def <=>(other) if nothing? other.nothing? ? 0 : -1 else other.nothing? ? 1 : just <=> other.just end end |
- (Boolean) just? Also known as: fulfilled?
Is this Maybe a Just (successfully fulfilled with a value)?
176 177 178 |
# File 'lib/concurrent/maybe.rb', line 176 def just? ! nothing? end |
- (Boolean) nothing? Also known as: rejected?
Is this Maybe a nothing (rejected with an exception upon fulfillment)?
184 185 186 |
# File 'lib/concurrent/maybe.rb', line 184 def nothing? @nothing != NONE end |
- (Object) or(other)
Return either the value of self or the given default value.
210 211 212 |
# File 'lib/concurrent/maybe.rb', line 210 def or(other) just? ? just : other end |