functional-ruby 0.7.7 → 1.0.0

data/doc/protocol.txt

@@ -0,0 +1,221 @@
+# @!macro [new] protocol
+#
+#   ## Rationale
+#   
+#   Traditional object orientation implements polymorphism inheritance. The *Is-A*
+#   relationship indicates that one object "is a" instance of another object.
+#   Implicit in this relationship, however, is the concept of [type](http://en.wikipedia.org/wiki/Data_type).
+#   Every Ruby object has a *type*, and that type is the name of its `Class` or
+#   `Module`. The Ruby runtime provides a number of reflective methods that allow
+#   objects to be interrogated for type information. The principal of thses is the
+#   `is_a?` (alias `kind_of`) method defined in class `Object`.
+#   
+#   Unlike many traditional object oriented languages, Ruby is a [dynamically typed](http://en.wikipedia.org/wiki/Dynamic_typing#DYNAMIC)
+#   language. Types exist but the runtime is free to cast one type into another
+#   at any time. Moreover, Ruby is a [duck typed](http://en.wikipedia.org/wiki/Duck_typing).
+#   If an object "walks like a duck and quacks like a duck then it must be a duck."
+#   When a method needs called on an object Ruby does not check the type of the object,
+#   it simply checks to see if the requested function exists with the proper
+#   [arity](http://en.wikipedia.org/wiki/Arity) and, if it does, dispatches the call.
+#   The duck type analogue to `is_a?` is `respond_to?`. Thus an object can be interrogated
+#   for its behavior rather than its type.
+#   
+#   Although Ruby offers several methods for reflecting on the behavior of a module/class/object,
+#   such as `method`, `instance_methods`, `const_defined?`, the aforementioned `respond_to?`,
+#   and others, Ruby lacks a convenient way to group collections of methods in any way that
+#   does not involve type. Both modules and classes provide mechanisms for combining
+#   methods into cohesive abstractions, but they both imply type. This is anathema to Ruby's
+#   dynamism and duck typing. What Ruby needs is a way to collect a group of method names
+#   and signatures into a cohesive collection that embraces duck typing and dynamic dispatch.
+#   This is what protocols do.
+#   
+#   ## Specifying
+#   
+#   A "protocol" is a loose collection of method, attribute, and constant names with optional
+#   arity values. The protocol definition does very little on its own. The power of protocols
+#   is that they provide a way for modules, classes, and objects to be interrogated with
+#   respect to common behavior, not common type. At the core a protocol is nothing more
+#   than a collection of `respond_to?` method calls that ask the question "Does this thing
+#   *behave* like this other thing."
+#   
+#   Protocols are specified with the `Functional::SpecifyProtocol` method. It takes one parameter,
+#   the name of the protocol, and a block which contains the protocol specification. This registers
+#   the protocol specification and makes it available for use later when interrogating ojects
+#   for their behavior.
+#   
+#   ### Defining Attributes, Methods, and Constants
+#   
+#   A single protocol specification can include definition for attributes, methods,
+#   and constants. Methods and attributes can be defined as class/module methods or
+#   as instance methods. Within the a protocol specification each item must include
+#   the symbolic name of the item being defined.
+#   
+#   ```ruby
+#   Functional::SpecifyProtocol(:KitchenSink) do
+#     instance_method     :instance_method
+#     class_method        :class_method
+#     attr_accessor       :attr_accessor
+#     attr_reader         :attr_reader
+#     attr_writer         :attr_writer
+#     class_attr_accessor :class_attr_accessor
+#     class_attr_reader   :class_attr_reader
+#     class_attr_writer   :class_attr_writer
+#     constant            :CONSTANT
+#   end
+#   ```
+#   
+#   Definitions for accessors are expanded at specification into the apprporiate
+#   method(s). Which means that this:
+#   
+#   ```ruby
+#   Functional::SpecifyProtocol(:Name) do
+#     attr_accessor :first
+#     attr_accessor :middle
+#     attr_accessor :last
+#     attr_accessor :suffix
+#   end
+#   ```
+#   
+#   is the same as:
+#   
+#   ```ruby
+#   Functional::SpecifyProtocol(:Name) do
+#     instance_method :first
+#     instance_method :first=
+#     instance_method :middle
+#     instance_method :middle=
+#     instance_method :last
+#     instance_method :last=
+#     instance_method :suffix
+#     instance_method :suffix=
+#   end
+#   ```
+#   
+#   Protocols only care about the methods themselves, not how they were declared.
+#   
+#   ### Arity
+#   
+#   In addition to defining *which* methods exist, the required method arity can
+#   indicated. Arity is optional. When no arity is given any arity will be expected.
+#   The arity rules follow those defined for the `#arity` method of Ruby's
+#   [Method class](http://www.ruby-doc.org/core-2.1.2/Method.html#method-i-arity):
+#   
+#   * Methods with a fixed number of arguments have a non-negative arity
+#   * Methods with optional arguments have an arity `-n - 1`, where n is the number of required arguments
+#   * Methods with a variable number of arguments have an arity of `-1`
+#   
+#   ```ruby
+#   Functional::SpecifyProtocol(:Foo) do
+#     instance_method :any_args
+#     instance_method :no_args, 0
+#     instance_method :three_args, 3
+#     instance_method :optional_args, -2
+#     instance_method :variable_args, -1
+#   end
+#   
+#   class Bar
+#   
+#     def any_args(a, b, c=1, d=2, *args)
+#     end
+#     
+#     def no_args
+#     end
+#   
+#     def three_args(a, b, c)
+#     end
+#   
+#     def optional_args(a, b=1, c=2)
+#     end
+#   
+#     def variable_args(*args)
+#     end
+#   end
+#   ```
+#   
+#   ## Reflection
+#   
+#   Once a protocol has been defined, any class, method, or object may be interrogated
+#   for adherence to one or more protocol specifications. The methods of the
+#   `Functional::Protocol` classes provide this capability. The `Satisfy?` method
+#   takes a module/class/object as the first parameter and one or more protocol names
+#   as the second and subsequent parameters. It returns a boolean value indicating
+#   whether the given object satisfies the protocol requirements:
+#   
+#   ```ruby
+#   Functional::SpecifyProtocol(:Queue) do
+#     instance_method :push, 1
+#     instance_method :pop, 0
+#     instance_method :length, 0
+#   end
+#   
+#   Functional::SpecifyProtocol(:List) do
+#     instance_method :[]=, 2
+#     instance_method :[], 1
+#     instance_method :each, 0
+#     instance_method :length, 0
+#   end
+#   
+#   Functional::Protocol::Satisfy?(Queue, :Queue)        #=> true
+#   Functional::Protocol::Satisfy?(Queue, :List)         #=> false
+#   
+#   list = [1, 2, 3]
+#   Functional::Protocol::Satisfy?(Array, :List, :Queue) #=> true
+#   Functional::Protocol::Satisfy?(list, :List, :Queue)  #=> true
+#   
+#   Functional::Protocol::Satisfy?(Hash, :Queue)         #=> false
+#   
+#   Functional::Protocol::Satisfy?('foo bar baz', :List) #=> false
+#   ```
+#   
+#   The `Satisfy!` method performs the exact same check but instead raises an exception
+#   when the protocol is not satisfied:
+#   
+#   ```
+#   2.1.2 :021 > Functional::Protocol::Satisfy!(Queue, :List)
+#   Functional::ProtocolError: Value (Class) 'Thread::Queue' does not behave as all of: :List.
+#   	from /Projects/functional-ruby/lib/functional/protocol.rb:67:in `error'
+#   	from /Projects/functional-ruby/lib/functional/protocol.rb:36:in `Satisfy!'
+#   	from (irb):21
+#     ...
+#   ```
+#   The `Functional::Protocol` module can be included within other classes
+#   to eliminate the namespace requirement when calling:
+#   
+#   ```ruby
+#   class MessageFormatter
+#     include Functional::Protocol
+#   
+#     def format(message)
+#       if Satisfy?(message, :Internal)
+#         format_internal_message(message)
+#       elsif Satisfy?(message, :Error)
+#         format_error_message(message)
+#       else
+#         format_generic_message(message)
+#       end
+#     end
+#   
+#     private
+#   
+#     def format_internal_message(message)
+#       # format the message...
+#     end
+#   
+#     def format_error_message(message)
+#       # format the message...
+#     end
+#   
+#     def format_generic_message(message)
+#       # format the message...
+#     end
+#   ```
+#   
+#   ## Inspiration
+#   
+#   Protocols and similar functionality exist in several other programming languages.
+#   A few languages that provided inspiration for this inplementation are:
+#   
+#   * Clojure [protocol](http://clojure.org/protocols)
+#   * Erlang [behaviours](http://www.erlang.org/doc/design_principles/des_princ.html#id60128)
+#   * Objective-C [protocol](https://developer.apple.com/library/ios/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/WorkingwithProtocols/WorkingwithProtocols.html)
+#     (and the corresponding Swift [protocol](https://developer.apple.com/library/prerelease/ios/documentation/Swift/Conceptual/Swift_Programming_Language/Protocols.html))

data/doc/record.txt

@@ -0,0 +1,144 @@
+# @!macro [new] record
+#
+#   ## Declaration
+#   
+#   A `Record` class is declared in a manner identical to that used with Ruby's `Struct`.
+#   The class method `new` is called with a list of one or more field names (symbols).
+#   A new class will then be dynamically generated along with the necessary reader
+#   attributes, one for each field. The newly created class will be anonymous and
+#   will mixin `Functional::AbstractStruct`. The best practice is to assign the newly
+#   created record class to a constant:
+#   
+#   ```ruby
+#   Customer = Functional::Record.new(:name, :address) #=> Customer
+#   ```
+#   
+#   Alternatively, the name of the record class, as a string, can be given as the
+#   first parameter. In this case the new record class will be created as a constant
+#   within the `Record` module:
+#   
+#   ```ruby
+#   Functional::Record.new("Customer", :name, :address) #=> Functional::Record::Customer
+#   ```
+#   
+#   **NOTE:** The `new` method of `Record` does not accept a block the way Ruby's `Struct`
+#   does. The block passed to the `new` method of `Record` is used to set mandatory fields
+#   and default values (see below). It is *not* used for additional class declarations.
+#   
+#   ### Construction
+#   
+#   Construction of a new object from a record is slightly different than for a Ruby `Struct`.
+#   The constructor for a struct class may take zero or more field values and will use those
+#   values to popuate the fields. The values passed to the constructor are assumed to be in
+#   the same order as the fields were defined. This works for a struct because it is
+#   mutable--the field values may be changed after instanciation. Therefore it is not
+#   necessary to provide all values to a stuct at creation. This is not the case for a
+#   record. A record is immutable. The values for all its fields must be set at instanciation
+#   because they cannot be changed later. When creating a new record object the constructor
+#   will accept a collection of field/value pairs in hash syntax and will create the new
+#   record with the given values:
+#   
+#   ```ruby
+#   Customer.new(name: 'Dave', address: '123 Main')
+#    #=> #<record Customer :name=>"Dave", :address=>"123 Main">
+#   
+#   Functional::Record::Customer.new(name: 'Dave', address: '123 Main')
+#    #=> #<record Functional::Record::Customer :name=>"Dave", :address=>"123 Main">
+#   ```
+#   
+#   ### Default Values
+#   
+#   By default, all record fields are set to `nil` at instanciation unless explicity set
+#   via the constructor. It is possible to specify default values other than `nil` for
+#   zero or more of the fields when a new record class is created. The `new` method of
+#   `Record` accepts a block which can be used to declare new default values:
+#   
+#   ```ruby
+#   Address = Functional::Record.new(:street_line_1, :street_line_2,
+#                                    :city, :state, :postal_code, :country) do
+#     default :state, 'Ohio'
+#     default :country, 'USA'
+#   end
+#    #=> Address
+#   ```
+#   
+#   When a new object is created from a record class with explicit default values, those
+#   values will be used for the appropriate fields when no other value is given at
+#   construction:
+#   
+#   ```ruby
+#   Address.new(street_line_1: '2401 Ontario St',
+#               city: 'Cleveland', postal_code: 44115)
+#    #=> #<record Address :street_line_1=>"2401 Ontario St", :street_line_2=>nil, :city=>"Cleveland", :state=>"Ohio", :postal_code=>44115, :country=>"USA">
+#   ```
+#   
+#   Of course, if a value for a field is given at construction that value will be used instead
+#   of the custom default:
+#   
+#   ```ruby
+#   Address.new(street_line_1: '1060 W Addison St',
+#               city: 'Chicago', state: 'Illinois', postal_code: 60613)
+#    #=> #<record Address :street_line_1=>"1060 W Addison St", :street_line_2=>nil, :city=>"Chicago", :state=>"Illinois", :postal_code=>60613, :country=>"USA">
+#   ```
+#   
+#   ### Mandatory Fields
+#   
+#   By default, all record fields are optional. It is perfectly legal for a record
+#   object to exist with all its fields set to `nil`. During declaration of a new record
+#   class the block passed to `Record.new` can also be used to indicate which fields
+#   are mandatory. When a new object is created from a record with mandatory fields
+#   an exception will be thrown if any of those fields are nil:
+#   
+#   ```ruby
+#   Name = Functional::Record.new(:first, :middle, :last, :suffix) do
+#     mandatory :first, :last
+#   end
+#    #=> Name
+#   
+#   Name.new(first: 'Joe', last: 'Armstrong')
+#    #=> #<record Name :first=>"Joe", :middle=>nil, :last=>"Armstrong", :suffix=>nil>
+#   
+#   Name.new(first: 'Matz') #=> ArgumentError: mandatory fields must not be nil
+#   ```
+#   
+#   Of course, declarations for default values and mandatory fields may be used
+#   together:
+#   
+#   ```ruby
+#   Person = Functional::Record.new(:first_name, :middle_name, :last_name,
+#                                   :street_line_1, :street_line_2,
+#                                   :city, :state, :postal_code, :country) do
+#     mandatory :first_name, :last_name
+#     mandatory :country
+#     default :state, 'Ohio'
+#     default :country, 'USA'
+#   end
+#    #=> Person
+#   ```
+#   
+#   ### Default Value Memoization
+#   
+#   Note that the block provided to `Record.new` is processed once and only once
+#   when the new record class is declared. Thereafter the results are memoized
+#   and copied (via `clone`, unless uncloneable) each time a new record object
+#   is created. Default values should be simple types like `String`, `Fixnum`,
+#   and `Boolean`. If complex operations need performed when setting default
+#   values the a `Class` should be used instead of a `Record`.
+#   
+#   ## Inspiration
+#   
+#   Neither struct nor records are new to computing. Both have been around for a very
+#   long time. Mutable structs can be found in many languages including
+#   [Ruby](http://www.ruby-doc.org/core-2.1.2/Struct.html),
+#   [Go](http://golang.org/ref/spec#Struct_types),
+#   [C](http://en.wikipedia.org/wiki/Struct_(C_programming_language)),
+#   and [C#](http://msdn.microsoft.com/en-us/library/ah19swz4.aspx),
+#   just to name a few. Immutable records exist primarily in functional languages
+#   like [Haskell](http://en.wikibooks.org/wiki/Haskell/More_on_datatypes#Named_Fields_.28Record_Syntax.29),
+#   Clojure, and Erlang. The latter two are the main influences for this implementation.
+#   
+#   * [Ruby Struct](http://www.ruby-doc.org/core-2.1.2/Struct.html)
+#   * [Clojure Datatypes](http://clojure.org/datatypes)
+#   * [Clojure *defrecord* macro](http://clojure.github.io/clojure/clojure.core-api.html#clojure.core/defrecord)
+#   * [Erlang Records (Reference)](http://www.erlang.org/doc/reference_manual/records.html)
+#   * [Erlang Records (Examples)](http://www.erlang.org/doc/programming_examples/records.html)

data/doc/thread_safety.txt

@@ -0,0 +1,8 @@
+# @!macro [new] thread_safe_immutable_object
+#
+#   @note This is an immutable, read-only, frozen, 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.

data/lib/functional.rb

@@ -1,26 +1,56 @@
-require 'functional/behavior'
-require 'functional/behaviour'
-require 'functional/catalog'
-require 'functional/collection'
-require 'functional/inflect'
+require 'functional/delay'
+require 'functional/either'
+require 'functional/memo'
+require 'functional/option'
 require 'functional/pattern_matching'
-require 'functional/platform'
-require 'functional/search'
-require 'functional/sort'
-require 'functional/utilities'
+require 'functional/protocol'
+require 'functional/protocol_info'
+require 'functional/record'
+require 'functional/type_check'
+require 'functional/union'
 require 'functional/version'
 
-Infinity = 1/0.0 unless defined?(Infinity)
-NaN = 0/0.0 unless defined?(NaN)
-
-$ENABLE_BEHAVIOR_CHECK_ON_CONSTRUCTION ||= true
+Functional::SpecifyProtocol(:Disposition) do
+  instance_method :value, 0
+  instance_method :value?, 0
+  instance_method :reason, 0
+  instance_method :reason?, 0
+  instance_method :fulfilled?, 0
+  instance_method :rejected?, 0
+end
 
+# Erlang, Clojure, and Go inspired functional programming tools to Ruby.
 module Functional
 
-  class << self
-    include Collection
-    include Inflect
-    include Search
-    include Sort
+  # Infinity
+  Infinity = 1/0.0
+
+  # Not a number
+  NaN = 0/0.0
+
+  # A gem-level configuration class.
+  # @!visibility private
+  class Configuration
+  end
+
+  # create the default configuration on load
+  # @!visibility private
+  @configuration = Configuration.new
+
+  # The current gem configutation.
+  #
+  # @return [Functional::Configuration]
+  #
+  # @!visibility private
+  def self.configuration
+    @configuration
+  end
+
+  # Perform gem-level configuration.
+  #
+  # @yield the configuration commands
+  # @yieldparam [Functional::Configuration] the current configuration object
+  def self.configure
+    yield(configuration)
   end
 end