functional-ruby 0.7.7 → 1.0.0

data/lib/functional/type_check.rb

@@ -0,0 +1,112 @@
+module Functional
+
+  # Supplies type-checking helpers whenever included.
+  #
+  # @see http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Actor/TypeCheck.html TypeCheck in Concurrent Ruby
+  module TypeCheck
+
+    # Performs an `is_a?` check of the given value object against the
+    # given list of modules and/or classes.
+    #
+    # @param [Object] value the object to interrogate
+    # @param [Module] types zero or more modules and/or classes to check
+    #   the value against
+    # @return [Boolean] true on success
+    def Type?(value, *types)
+      types.any? { |t| value.is_a? t }
+    end
+    module_function :Type?
+
+    # Performs an `is_a?` check of the given value object against the
+    # given list of modules and/or classes. Raises an exception on failure.
+    #
+    # @param [Object] value the object to interrogate
+    # @param [Module] types zero or more modules and/or classes to check
+    #   the value against
+    # @return [Object] the value object
+    #
+    # @raise [Functional::TypeError] when the check fails
+    def Type!(value, *types)
+      Type?(value, *types) or
+        TypeCheck.error(value, 'is not', types)
+      value
+    end
+    module_function :Type!
+
+    # Is the given value object is an instance of or descendant of
+    # one of the classes/modules in the given list?
+    #
+    # Performs the check using the `===` operator.
+    #
+    # @param [Object] value the object to interrogate
+    # @param [Module] types zero or more modules and/or classes to check
+    #   the value against
+    # @return [Boolean] true on success
+    def Match?(value, *types)
+      types.any? { |t| t === value }
+    end
+    module_function :Match?
+
+    # Is the given value object is an instance of or descendant of
+    # one of the classes/modules in the given list?  Raises an exception
+    # on failure.
+    #
+    # Performs the check using the `===` operator.
+    #
+    # @param [Object] value the object to interrogate
+    # @param [Module] types zero or more modules and/or classes to check
+    #   the value against
+    # @return [Object] the value object
+    #
+    # @raise [Functional::TypeError] when the check fails
+    def Match!(value, *types)
+      Match?(value, *types) or
+        TypeCheck.error(value, 'is not matching', types)
+      value
+    end
+    module_function :Match!
+
+    # Is the given class a subclass or exact match of one or more
+    # of the modules and/or classes in the given list?
+    #
+    # @param [Class] value the class to interrogate
+    # @param [Class] types zero or more classes to check the value against
+    #   the value against
+    # @return [Boolean] true on success
+    def Child?(value, *types)
+      Type?(value, Class) &&
+        types.any? { |t| value <= t }
+    end
+    module_function :Child?
+
+    # Is the given class a subclass or exact match of one or more
+    # of the modules and/or classes in the given list?
+    #
+    # @param [Class] value the class to interrogate
+    # @param [Class] types zero or more classes to check the value against
+    # @return [Class] the value class
+    #
+    # @raise [Functional::TypeError] when the check fails
+    def Child!(value, *types)
+      Child?(value, *types) or
+        TypeCheck.error(value, 'is not child', types)
+      value
+    end
+    module_function :Child!
+
+    private
+
+    # Create a {Functional::TypeError} object from the given data.
+    #
+    # @param [Object] value the class/method that was being interrogated
+    # @param [String] message the message fragment to inject into the error
+    # @param [Object] types list of modules and/or classes that were being
+    #   checked against the value object
+    #
+    # @raise [Functional::TypeError] the formatted exception object
+    def self.error(value, message, types)
+      raise TypeError,
+        "Value (#{value.class}) '#{value}' #{message} any of: #{types.join('; ')}."
+    end
+  end
+end

data/lib/functional/union.rb

@@ -0,0 +1,152 @@
+require_relative 'abstract_struct'
+
+module Functional
+
+  # An immutable data structure with multiple fields, only one of which
+  # can be set at any given time. A `Union` is a convenient way to bundle a
+  # number of field attributes together, using accessor methods, without having
+  # to write an explicit class.
+  #
+  # The `Union` module generates new `AbstractStruct` subclasses that hold a set of
+  # fields with one and only one value associated with a single field. For each
+  # field a reader method is created along with a predicate and a factory. The
+  # predicate method indicates whether or not the give field is set. The reader
+  # method returns the value of that field or `nil` when not set. The factory
+  # creates a new union with the appropriate field set with the given value.
+  #
+  # A `Union` is very similar to a Ruby `Struct` and shares many of its behaviors
+  # and attributes. Where a `Struct` can have zero or more values, each of which is
+  # assiciated with a field, a `Union` can have one and only one value. Unlike a
+  # Ruby `Struct`, a `Union` is immutable: its value is set at construction and
+  # it can never be changed. Divergence between the two classes derive from these
+  # two core differences.
+  #
+  # @example Creating a New Class
+  # 
+  #   LeftRightCenter = Functional::Union.new(:left, :right, :center) #=> LeftRightCenter
+  #   LeftRightCenter.ancestors #=> [LeftRightCenter, Functional::AbstractStruct... ]
+  #   LeftRightCenter.fields   #=> [:left, :right, :center]
+  #   
+  #   prize = LeftRightCenter.right('One million dollars!') #=> #<union LeftRightCenter... >
+  #   prize.fields #=> [:left, :right, :center]
+  #   prize.values  #=> [nil, "One million dollars!", nil]
+  #   
+  #   prize.left?   #=> false
+  #   prize.right?  #=> true
+  #   prize.center? #=> false
+  #   
+  #   prize.left    #=> nil
+  #   prize.right   #=> "One million dollars!"
+  #   prize.center  #=> nil
+  #
+  # @example Registering a New Class with Union
+  #
+  #   Functional::Union.new('Suit', :clubs, :diamonds, :hearts, :spades)
+  #    #=> Functional::Union::Suit
+  #
+  #   Functional::Union::Suit.hearts('Queen')
+  #    #=> #<union Functional::Union::Suit :clubs=>nil, :diamonds=>nil, :hearts=>"Queen", :spades=>nil>
+  #
+  # @see Functional::AbstractStruct
+  # @see Functional::Union
+  # @see http://www.ruby-doc.org/core-2.1.2/Struct.html Ruby `Struct` class
+  # @see http://en.wikipedia.org/wiki/Union_type "Union type" on Wikipedia
+  #
+  # @!macro thread_safe_immutable_object
+  module Union
+    extend self
+
+    # Create a new union class with the given fields.
+    #
+    # @return [Functional::AbstractStruct] the new union subclass
+    # @raise [ArgumentError] no fields specified
+    def new(*fields)
+      raise ArgumentError.new('no fields provided') if fields.empty?
+      build(fields)
+    end
+
+    private
+
+    # Use the given `AbstractStruct` class and build the methods necessary
+    # to support the given data fields.
+    #
+    # @param [Array] fields the list of symbolic names for all data fields
+    # @return [Functional::AbstractStruct] the union class
+    def build(fields)
+      union, fields = AbstractStruct.define_class(self, :union, fields)
+      union.private_class_method(:new)
+      define_properties(union)
+      define_initializer(union)
+      fields.each do |field|
+        define_reader(union, field)
+        define_predicate(union, field)
+        define_factory(union, field)
+      end
+      union
+    end
+
+    # Define the `field` and `value` attribute readers on the given union class.
+    #
+    # @param [Functional::AbstractStruct] union the new union class
+    # @return [Functional::AbstractStruct] the union class
+    def define_properties(union)
+      union.send(:attr_reader, :field)
+      union.send(:attr_reader, :value)
+      union
+    end
+
+    # Define a predicate method on the given union class for the given data field.
+    #
+    # @param [Functional::AbstractStruct] union the new union class
+    # @param [Symbol] field symbolic name of the current data field
+    # @return [Functional::AbstractStruct] the union class
+    def define_predicate(union, field)
+      union.send(:define_method, "#{field}?".to_sym) do
+        @field == field
+      end
+      union
+    end
+
+    # Define a reader method on the given union class for the given data field.
+    #
+    # @param [Functional::AbstractStruct] union the new union class
+    # @param [Symbol] field symbolic name of the current data field
+    # @return [Functional::AbstractStruct] the union class
+    def define_reader(union, field)
+      union.send(:define_method, field) do
+        send("#{field}?".to_sym) ? @value : nil
+      end
+      union
+    end
+
+    # Define an initializer method on the given union class.
+    #
+    # @param [Functional::AbstractStruct] union the new union class
+    # @return [Functional::AbstractStruct] the union class
+    def define_initializer(union)
+      union.send(:define_method, :initialize) do |field, value|
+        @field = field
+        @value = value
+        data = fields.reduce({}) do |memo, field|
+          memo[field] = ( field == @field ? @value : nil )
+          memo
+        end
+        set_data_hash(data)
+        set_values_array(data.values)
+      end
+      union
+    end
+
+    # Define a factory method on the given union class for the given data field.
+    #
+    # @param [Functional::AbstractStruct] union the new union class
+    # @param [Symbol] field symbolic name of the current data field
+    # @return [Functional::AbstractStruct] the union class
+    def define_factory(union, field)
+      union.class.send(:define_method, field) do |value|
+        new(field, value).freeze
+      end
+      union
+    end
+  end
+end

data/lib/functional/version.rb

@@ -1,3 +1,5 @@
 module Functional
-  VERSION = '0.7.7'
+
+  # The current gem version.
+  VERSION = '1.0.0'
 end

data/spec/functional/abstract_struct_shared.rb

@@ -0,0 +1,154 @@
+shared_examples :abstract_struct do
+
+  specify { Functional::Protocol::Satisfy! struct_class, :Struct }
+
+  let(:other_struct) do
+    Class.new do
+      include Functional::AbstractStruct
+      self.fields = [:foo, :bar, :baz].freeze
+      self.datatype = :other_struct
+    end
+  end
+
+  context 'field collection' do
+
+    it 'contains all possible fields' do
+      expected_fields.each do |field|
+        expect(struct_class.fields).to include(field)
+      end
+    end
+
+    it 'is frozen' do
+      expect(struct_class.fields).to be_frozen
+    end
+
+    it 'does not overwrite fields for other structs' do
+      expect(struct_class.fields).to_not eq other_struct.fields
+    end
+
+    it 'is the same when called on the class and on an object' do
+      expect(struct_class.fields).to eq struct_object.fields
+    end
+  end
+
+  context 'readers' do
+
+    specify '#values returns all values in an array' do
+      expect(struct_object.values).to eq expected_values
+    end
+
+    specify '#values is frozen' do
+      expect(struct_object.values).to be_frozen
+    end
+
+    specify 'exist for each field' do
+      expected_fields.each do |field|
+        expect(struct_object).to respond_to(field)
+        expect(struct_object.method(field).arity).to eq 0
+      end
+    end
+
+    specify 'return the appropriate value all fields' do
+      expected_fields.each_with_index do |field, i|
+        expect(struct_object.send(field)).to eq expected_values[i]
+      end
+    end
+  end
+
+  context 'enumeration' do
+
+    specify '#each_pair with a block iterates over all fields and values' do
+      fields = []
+      values = []
+
+      struct_object.each_pair do |field, value|
+        fields << field
+        values << value
+      end
+
+      expect(fields).to eq struct_object.fields
+      expect(values).to eq struct_object.values
+    end
+
+    specify '#each_pair without a block returns an Enumerable' do
+      expect(struct_object.each_pair).to be_a Enumerable
+    end
+
+    specify '#each with a block iterates over all values' do
+      values = []
+
+      struct_object.each do |value|
+        values << value
+      end
+
+      expect(values).to eq struct_object.values
+    end
+
+    specify '#each without a block returns an Enumerable' do
+      expect(struct_object.each).to be_a Enumerable
+    end
+  end
+
+  context 'reflection' do
+
+    specify 'always creates frozen objects' do
+      expect(struct_object).to be_frozen
+    end
+
+    specify 'asserts equality for two structs of the same class with equal values' do
+      other = struct_object.dup
+
+      expect(struct_object).to eq other
+      expect(struct_object).to eql other
+    end
+
+    specify 'rejects equality for two structs of different classes' do
+      other = Struct.new(*expected_fields).new(*expected_values)
+
+      expect(struct_object).to_not eq other
+      expect(struct_object).to_not eql other
+    end
+
+    specify 'rejects equality for two structs of the same class with different values' do
+      expect(struct_object).to_not eq other_object
+      expect(struct_object).to_not eql other_struct
+    end
+
+    specify '#to_h returns a Hash with all field/value pairs' do
+      hsh = struct_object.to_h
+
+      expect(hsh.keys).to eq struct_object.fields
+      expect(hsh.values).to eq struct_object.values
+    end
+
+    specify '#inspect result is enclosed in brackets' do
+      expect(struct_object.inspect).to match(/^#</)
+      expect(struct_object.inspect).to match(/>$/)
+    end
+
+    specify '#inspect result has lowercase class name as first element' do
+      struct = described_class.to_s.split('::').last.downcase
+      expect(struct_object.inspect).to match(/^#<#{struct} /)
+    end
+
+    specify '#inspect includes all field/value pairs' do
+      struct_object.fields.each_with_index do |field, i|
+        value_regex = "\"?#{struct_object.values[i]}\"?"
+        expect(struct_object.inspect).to match(/:#{field}=>#{value_regex}/)
+      end
+    end
+
+    specify '#inspect is aliased as #to_s' do
+      expect(struct_object.inspect).to eq struct_object.to_s
+    end
+
+    specify '#length returns the number of fields' do
+      expect(struct_object.length).to eq struct_class.fields.length
+      expect(struct_object.length).to eq expected_fields.length
+    end
+
+    specify 'aliases #length as #size' do
+      expect(struct_object.length).to eq struct_object.size
+    end
+  end
+end

data/spec/functional/complex_pattern_matching_spec.rb

@@ -0,0 +1,205 @@
+require 'spec_helper'
+require 'ostruct'
+
+class Bar
+  def greet
+    return 'Hello, World!'
+  end
+end
+
+class Foo < Bar
+  include Functional::PatternMatching
+
+  attr_accessor :name
+
+  defn(:initialize) { @name = 'baz' }
+  defn(:initialize, _) {|name| @name = name.to_s }
+
+  defn(:greet, _) do |name|
+    "Hello, #{name}!"
+  end
+
+  defn(:greet, :male, _) { |name|
+    "Hello, Mr. #{name}!"
+  }
+  defn(:greet, :female, _) { |name|
+    "Hello, Ms. #{name}!"
+  }
+  defn(:greet, nil, _) { |name|
+    "Goodbye, #{name}!"
+  }
+  defn(:greet, _, _) { |_, name|
+    "Hello, #{name}!"
+  }
+
+  defn(:hashable, _, {foo: :bar}, _) { |_, opts, _|
+    :foo_bar
+  }
+  defn(:hashable, _, {foo: _, bar: _}, _) { |_, f, b, _|
+    [f, b]
+  }
+  defn(:hashable, _, {foo: _}, _) { |_, f, _|
+    f
+  }
+  defn(:hashable, _, {}, _) {
+    :empty
+  }
+  defn(:hashable, _, _, _) { |_, _, _|
+    :unbound
+  }
+
+  defn(:options, _) { |opts|
+    opts
+  }
+
+  defn(:recurse) {
+    'w00t!'
+  }
+  defn(:recurse, :match) {
+    recurse()
+  }
+  defn(:recurse, :super) {
+    greet()
+  }
+  defn(:recurse, :instance) {
+    @name
+  }
+  defn(:recurse, _) { |arg|
+    arg
+  }
+
+  defn(:concat, Integer, Integer) { |first, second|
+    first + second
+  }
+  defn(:concat, Integer, String) { |first, second|
+    "#{first} #{second}"
+  }
+  defn(:concat, String, String) { |first, second|
+    first + second
+  }
+  defn(:concat, Integer, UNBOUND) { |first, second|
+    first + second.to_i
+  }
+
+  defn(:all, :one, ALL) { |args|
+    args
+  }
+  defn(:all, :one, Integer, ALL) { |int, args|
+    [int, args]
+  }
+  defn(:all, 1, _, ALL) { |var, args|
+    [var, args]
+  }
+  defn(:all, ALL) { | args|
+    args
+  }
+
+  defn(:old_enough, _){ true }.when{|x| x >= 16 }
+  defn(:old_enough, _){ false }
+
+  defn(:right_age, _) {
+    true
+  }.when{|x| x >= 16 && x <= 104 }
+
+  defn(:right_age, _) {
+    false
+  }
+
+  defn(:wrong_age, _) {
+    true
+  }.when{|x| x < 16 || x > 104 }
+
+  defn(:wrong_age, _) {
+    false
+  }
+  end
+
+class Baz < Foo
+  def boom_boom_room
+    'zoom zoom zoom'
+  end
+  def who(first, last)
+    [first, last].join(' ')
+  end
+end
+
+class Fizzbuzz < Baz
+  include Functional::PatternMatching
+  defn(:who, Integer) { |count|
+    (1..count).each.reduce(:+)
+  }
+  defn(:who) { 0 }
+end
+
+describe 'complex pattern matching' do
+
+  let(:name) { 'Pattern Matcher' }
+  subject { Foo.new(name) }
+
+  specify { expect(subject.greet).to eq 'Hello, World!' }
+
+  specify { expect(subject.greet('Jerry')).to eq 'Hello, Jerry!' }
+
+  specify { expect(subject.greet(:male, 'Jerry')).to eq 'Hello, Mr. Jerry!' }
+  specify { expect(subject.greet(:female, 'Jeri')).to eq 'Hello, Ms. Jeri!' }
+  specify { expect(subject.greet(:unknown, 'Jerry')).to eq 'Hello, Jerry!' }
+  specify { expect(subject.greet(nil, 'Jerry')).to eq 'Goodbye, Jerry!' }
+  specify {
+    expect { Foo.new.greet(1,2,3,4,5,6,7) }.to raise_error(NoMethodError)
+  }
+
+  specify { expect(subject.options(bar: :baz, one: 1, many: 2)).to eq({bar: :baz, one: 1, many: 2}) }
+
+  specify { expect(subject.hashable(:male, {foo: :bar}, :female)).to eq :foo_bar }
+  specify { expect(subject.hashable(:male, {foo: :baz}, :female)).to eq :baz }
+  specify { expect(subject.hashable(:male, {foo: 1, bar: 2}, :female)).to eq [1, 2] }
+  specify { expect(subject.hashable(:male, {foo: 1, baz: 2}, :female)).to eq 1 }
+  specify { expect(subject.hashable(:male, {bar: :baz}, :female)).to eq :unbound }
+  specify { expect(subject.hashable(:male, {}, :female)).to eq :empty }
+
+  specify { expect(subject.recurse).to eq 'w00t!' }
+  specify { expect(subject.recurse(:match)).to eq 'w00t!' }
+  specify { expect(subject.recurse(:super)).to eq 'Hello, World!' }
+  specify { expect(subject.recurse(:instance)).to eq name }
+  specify { expect(subject.recurse(:foo)).to eq :foo }
+
+  specify { expect(subject.concat(1, 1)).to eq 2 }
+  specify { expect(subject.concat(1, 'shoe')).to eq '1 shoe' }
+  specify { expect(subject.concat('shoe', 'fly')).to eq 'shoefly' }
+  specify { expect(subject.concat(1, 2.9)).to eq 3 }
+
+  specify { expect(subject.all(:one, 'a', 'bee', :see)).to eq(['a', 'bee', :see]) }
+  specify { expect(subject.all(:one, 1, 'bee', :see)).to eq([1, 'bee', :see]) }
+  specify { expect(subject.all(1, 'a', 'bee', :see)).to eq(['a', ['bee', :see]]) }
+  specify { expect(subject.all('a', 'bee', :see)).to eq(['a', 'bee', :see]) }
+  specify { expect { subject.all }.to raise_error(NoMethodError) }
+
+  specify { expect(subject.old_enough(20)).to be true }
+  specify { expect(subject.old_enough(10)).to be false }
+
+  specify { expect(subject.right_age(20)).to be true }
+  specify { expect(subject.right_age(10)).to be false }
+  specify { expect(subject.right_age(110)).to be false }
+
+  specify { expect(subject.wrong_age(20)).to be false }
+  specify { expect(subject.wrong_age(10)).to be true }
+  specify { expect(subject.wrong_age(110)).to be true }
+
+  context 'inheritance' do
+
+    specify { expect(Fizzbuzz.new.greet(:male, 'Jerry')).to eq 'Hello, Mr. Jerry!' }
+    specify { expect(Fizzbuzz.new.greet(:female, 'Jeri')).to eq 'Hello, Ms. Jeri!' }
+    specify { expect(Fizzbuzz.new.greet(:unknown, 'Jerry')).to eq 'Hello, Jerry!' }
+    specify { expect(Fizzbuzz.new.greet(nil, 'Jerry')).to eq 'Goodbye, Jerry!' }
+
+    specify { expect(Fizzbuzz.new.who(5)).to eq 15 }
+    specify { expect(Fizzbuzz.new.who()).to eq 0 }
+    specify { 
+      expect {
+        Fizzbuzz.new.who('Jerry', 'secret middle name', "D'Antonio")
+      }.to raise_error(NoMethodError)
+    }
+
+    specify { expect(Fizzbuzz.new.boom_boom_room).to eq 'zoom zoom zoom' }
+  end
+end