functional-ruby 1.1.0 → 1.2.0

data/doc/protocol.txt

@@ -1,221 +0,0 @@
-# @!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

@@ -1,207 +0,0 @@
-# @!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`.
-#
-#   ### Why Declaration Differs from Ruby's Struct
-#
-#   Those familiar with Ruby's `Struct` class will notice one important
-#   difference when declaring a `Record`: the block passes to `new` cannot be
-#   used to define additional methods. When declaring a new class created from a
-#   Ruby `Struct` the block can perform any additional class definition that
-#   could be done had the class be defined normally. The excellent
-#   [Values](https://github.com/tcrayford/Values) supports this same behavior.
-#   `Record` does not allow additional class definitions during declaration for
-#   one simple reason: doing so violates two very important tenets of functional
-#   programming. Specifically, immutability and the separation of data from
-#   operations.
-#
-#   `Record` exists for the purpose of creating immutable objects. If additional
-#   instance methods were to be defined on a record class it would be possible
-#   to violate immutability. Not only could additional, mutable state be added
-#   to the class, but the existing immutable attributes could be overridden by
-#   mutable methods. The security of providing an immutable object would be
-#   completely shattered, thus defeating the original purpose of the record
-#   class. Of course it would be possible to allow this feature and trust the
-#   programmer to not violate the intended immutability of class, but opening
-#   `Record` to the *possibility* of immutability violation is unnecessary and
-#   unwise.
-#
-#   More important than the potential for immutability violations is the fact
-#   the adding additional methods to a record violates the principal of
-#   separating data from operations on that data. This is one of the core ideas
-#   in functional programming. Data is defined in pure structures that contain
-#   no behavior and operations on that data are provided by polymorphic
-#   functions. This may seem counterintuitive to object oriented programmers,
-#   but that is the nature of functional programming. Adding behavior to a
-#   record, even when that behavior does not violate immutability, is still
-#   anathema to functional programming, and it is why records in languages like
-#   Erlang and Clojure do not have functions defined within them.
-#
-#   Should additional methods need defined on a `Record` class, the appropriate
-#   practice is to declare the record class then declare another class which
-#   extends the record. The record class remains pure data and the subclass
-#   contains additional operations on that data.
-#
-#   ```ruby
-#   NameRecord = Functional::Record.new(:first, :middle, :last, :suffix) do
-#     mandatory :first, :last
-#   end
-#   
-#   class Name < NameRecord
-#     def full_name
-#       "#{first} #{last}"
-#     end
-#   
-#     def formal_name
-#       name = [first, middle, last].select{|s| ! s.to_s.empty?}.join(' ')
-#       suffix.to_s.empty? ? name : name + ", #{suffix}"
-#     end
-#   end
-#
-#   jerry = Name.new(first: 'Jerry', last: "D'Antonio")
-#   ted   = Name.new(first: 'Ted', middle: 'Theodore', last: 'Logan', suffix: 'Esq.')
-#
-#   jerry.formal_name #=> "Jerry D'Antonio"
-#   ted.formal_name   #=> "Ted Theodore Logan, Esq."
-#   ```
-#   
-#   ## 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

@@ -1,17 +0,0 @@
-# @!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.
-#
-# @!macro [new] thread_safe_final_object
-#
-#   @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.