Class: Functional::Either

Inherits:
Synchronization::Object
  • Object
show all
Defined in:
lib/functional/either.rb

Overview

Note:

This is a write-once, read-many, thread safe object that can be used in concurrent systems. Thread safety guarantees cannot be made about objects contained within this object, however. Ruby variables are mutable references to mutable objects. This cannot be changed. The best practice it to only encapsulate immutable, frozen, or thread safe objects. Ultimately, thread safety is the responsibility of the programmer.

The ‘Either` type represents a value of one of two possible types (a disjoint union). It is an immutable structure that contains one and only one value. That value can be stored in one of two virtual position, `left` or `right`. The position provides context for the encapsulated data.

One of the main uses of ‘Either` is as a return value that can indicate either success or failure. Object oriented programs generally report errors through either state or exception handling, neither of which work well in functional programming. In the former case, a method is called on an object and when an error occurs the state of the object is updated to reflect the error. This does not translate well to functional programming because they eschew state and mutable objects. In the latter, an exception handling block provides branching logic when an exception is thrown. This does not translate well to functional programming because it eschews side effects like structured exception handling (and structured exception handling tends to be very expensive). `Either` provides a powerful and easy-to-use alternative.

A function that may generate an error can choose to return an immutable ‘Either` object in which the position of the value (left or right) indicates the nature of the data. By convention, a `left` value indicates an error and a `right` value indicates success. This leaves the caller with no ambiguity regarding success or failure, requires no persistent state, and does not require expensive exception handling facilities.

‘Either` provides several aliases and convenience functions to facilitate these failure/success conventions. The `left` and `right` functions, including their derivatives, are mirrored by `reason` and `value`. Failure is indicated by the presence of a `reason` and success is indicated by the presence of a `value`. When an operation has failed the either is in a `rejected` state, and when an operation has successed the either is in a `fulfilled` state. A common convention is to use a Ruby `Exception` as the `reason`. The factory method `error` facilitates this. The semantics and conventions of `reason`, `value`, and their derivatives follow the conventions of the Concurrent Ruby gem.

The ‘left`/`right` and `reason`/`value` methods are not mutually exclusive. They can be commingled and still result in functionally correct code. This practice should be avoided, however. Consistent use of either `left`/`right` or `reason`/`value` against each `Either` instance will result in more expressive, intent-revealing code.

Examples:


require 'uri'

def web_host(url)
  uri = URI(url)
  if uri.scheme != 'http'
    Functional::Either.left('Invalid HTTP URL')
  else
    Functional::Either.right(uri.host)
  end
end

good = web_host('http://www.concurrent-ruby.com')
good.right? #=> true
good.right  #=> "www.concurrent-ruby"
good.left #=> nil

good = web_host('bogus')
good.right? #=> false
good.right  #=> nil
good.left #=> "Invalid HTTP URL"

See Also:

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.error(message = nil, clazz = StandardError) ⇒ Either

Create an ‘Either` with the left value set to an `Exception` object complete with message and backtrace. This is a convenience method for supporting the reason/value convention with the reason always being an `Exception` object. When no exception class is given `StandardError` will be used. When no message is given the default message for the given error class will be used.

Examples:


either = Functional::Either.error("You're a bad monkey, Mojo Jojo")
either.fulfilled? #=> false
either.rejected?  #=> true
either.value      #=> nil
either.reason     #=> #<StandardError: You're a bad monkey, Mojo Jojo>

Parameters:

  • message (String) (defaults to: nil) —

    The message for the new error object.

  • clazz (Exception) (defaults to: StandardError) —

    The class for the new error object.

Returns:

  • (Either) —

    A new either with an error object as the left value.



133
134
135
136
137
 
# File 'lib/functional/either.rb', line 133

def error(message = nil, clazz = StandardError)
  ex = clazz.new(message)
  ex.set_backtrace(caller)
  left(ex)
end

.iff(lvalue, rvalue, condition = NO_VALUE) { ... } ⇒ Either

If the condition satisfies, return the given A in left, otherwise, return the given B in right.

Parameters:

  • lvalue (Object) —

    The left value to use if the condition satisfies.

  • rvalue (Object) —

    The right value to use if the condition does not satisfy.

  • condition (Boolean) (defaults to: NO_VALUE) —

    The condition to test (when no block given).

Yields:

  • The condition to test (when no condition given).

Returns:

  • (Either) —

    A constructed either based on the given condition.

Raises:

  • (ArgumentError) —

    When both a condition and a block are given.



204
205
206
207
208
 
# File 'lib/functional/either.rb', line 204

def self.iff(lvalue, rvalue, condition = NO_VALUE)
  raise ArgumentError.new('requires either a condition or a block, not both') if condition != NO_VALUE && block_given?
  condition = block_given? ? yield : !! condition
  condition ? left(lvalue) : right(rvalue)
end

.left(value) ⇒ Either

Construct a left value of either.

Parameters:

  • value (Object) —

    The value underlying the either.

Returns:

  • (Either) —

    A new either with the given left value.



101
102
103
 
# File 'lib/functional/either.rb', line 101

def left(value)
  new(value, true).freeze
end

.reason ⇒ Either

Construct a left value of either.

Parameters:

  • value (Object) —

    The value underlying the either.

Returns:

  • (Either) —

    A new either with the given left value.



104
105
106
 
# File 'lib/functional/either.rb', line 104

def left(value)
  new(value, true).freeze
end

.right(value) ⇒ Either

Construct a right value of either.

Parameters:

  • value (Object) —

    The value underlying the either.

Returns:

  • (Either) —

    A new either with the given right value.



110
111
112
 
# File 'lib/functional/either.rb', line 110

def right(value)
  new(value, false).freeze
end

.value ⇒ Either

Construct a right value of either.

Parameters:

  • value (Object) —

    The value underlying the either.

Returns:

  • (Either) —

    A new either with the given right value.



113
114
115
 
# File 'lib/functional/either.rb', line 113

def right(value)
  new(value, false).freeze
end

Instance Method Details

#either(lproc, rproc) ⇒ Object

The catamorphism for either. Folds over this either breaking into left or right.

Parameters:

  • lproc (Proc) —

    The function to call if this is left.

  • rproc (Proc) —

    The function to call if this is right.

Returns:

  • (Object) —

    The reduced value.



190
191
192
 
# File 'lib/functional/either.rb', line 190

def either(lproc, rproc)
  left? ? lproc.call(left) : rproc.call(right)
end

#left ⇒ Object Also known as: reason

Projects this either as a left.

Returns:

  • (Object) —

    The left value or ‘nil` when `right`.



143
144
145
 
# File 'lib/functional/either.rb', line 143

def left
  left? ? to_h[:left] : nil
end

#left? ⇒ Boolean Also known as: reason?, rejected?

Returns true if this either is a left, false otherwise.

Returns:

  • (Boolean) —

    ‘true` if this either is a left, `false` otherwise.



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

def left?
  @is_left
end

#right ⇒ Object Also known as: value

Projects this either as a right.

Returns:

  • (Object) —

    The right value or ‘nil` when `left`.



151
152
153
 
# File 'lib/functional/either.rb', line 151

def right
  right? ? to_h[:right] : nil
end

#right? ⇒ Boolean Also known as: value?, fulfilled?

Returns true if this either is a right, false otherwise.

Returns:

  • (Boolean) —

    ‘true` if this either is a right, `false` otherwise.



168
169
170
 
# File 'lib/functional/either.rb', line 168

def right?
  ! left?
end

#swap ⇒ Either

If this is a left, then return the left value in right, or vice versa.

Returns:

  • (Either) —

    The value of this either swapped to the opposing side.



177
178
179
180
181
182
183
 
# File 'lib/functional/either.rb', line 177

def swap
  if left?
    self.class.send(:new, left, false)
  else
    self.class.send(:new, right, true)
  end
end