functional-ruby 1.0.0 → 1.1.0

data/lib/functional/type_check.rb

@@ -3,6 +3,8 @@ module Functional
   # Supplies type-checking helpers whenever included.
   #
   # @see http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Actor/TypeCheck.html TypeCheck in Concurrent Ruby
+  #
+  # @since 1.0.0
   module TypeCheck
 
     # Performs an `is_a?` check of the given value object against the

data/lib/functional/union.rb

@@ -52,6 +52,8 @@ module Functional
   # @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
   #
+  # @since 1.0.0
+  #
   # @!macro thread_safe_immutable_object
   module Union
     extend self

data/lib/functional/value_struct.rb

@@ -0,0 +1,144 @@
+module Functional
+
+  # A variation on Ruby's `OpenStruct` in which all fields are immutable and
+  # set at instantiation. For compatibility with {Functional::FinalStruct}, 
+  # predicate methods exist for all potential fields and these predicates
+  # indicate if the field has been set. Calling a predicate method for a field
+  # that does not exist on the struct will return false.
+  #
+  # Unlike {Functional::Record}, which returns a new class which can be used to
+  # create immutable objects, `ValueStruct` creates simple immutable objects.
+  #
+  # @example Instanciation
+  #   name = Functional::ValueStruct.new(first: 'Douglas', last: 'Adams')
+  #
+  #   name.first   #=> 'Douglas'
+  #   name.last    #=> 'Adams'
+  #   name.first?  #=> true
+  #   name.last?   #=> true
+  #   name.middle? #=> false
+  #
+  # @since 1.1.0
+  #
+  # @see Functional::Record
+  # @see Functional::FinalStruct
+  # @see http://www.ruby-doc.org/stdlib-2.1.2/libdoc/ostruct/rdoc/OpenStruct.html
+  #
+  # @!macro thread_safe_immutable_object
+  class ValueStruct
+
+    def initialize(attributes)
+      raise ArgumentError.new('attributes must be given as a hash') unless attributes.respond_to?(:each_pair)
+      @attribute_hash = {}
+      attributes.each_pair do |field, value|
+        set_attribute(field, value)
+      end
+      @attribute_hash.freeze
+      self.freeze
+    end
+
+    # Get the value of the given field.
+    #
+    # @param [Symbol] field the field to retrieve the value for
+    # @return [Object] the value of the field is set else nil
+    def get(field)
+      @attribute_hash[field.to_sym]
+    end
+    alias_method :[], :get
+
+    # Check the internal hash to unambiguously verify that the given
+    # attribute has been set.
+    #
+    # @param [Symbol] field the field to get the value for
+    # @return [Boolean] true if the field has been set else false
+    def set?(field)
+      @attribute_hash.has_key?(field.to_sym)
+    end
+
+    # Get the current value of the given field if already set else return the given
+    # default value.
+    #
+    # @param [Symbol] field the field to get the value for
+    # @param [Object] default the value to return if the field has not been set
+    # @return [Object] the value of the given field else the given default value
+    def fetch(field, default)
+      @attribute_hash.fetch(field.to_sym, default)
+    end
+
+    # Calls the block once for each attribute, passing the key/value pair as parameters.
+    # If no block is given, an enumerator is returned instead.
+    #
+    # @yieldparam [Symbol] field the struct field for the current iteration
+    # @yieldparam [Object] value the value of the current field
+    #
+    # @return [Enumerable] when no block is given
+    def each_pair
+      return enum_for(:each_pair) unless block_given?
+      @attribute_hash.each do |field, value|
+        yield(field, value)
+      end
+    end
+
+    # Converts the `ValueStruct` to a `Hash` with keys representing each attribute
+    # (as symbols) and their corresponding values.
+    # 
+    # @return [Hash] a `Hash` representing this struct
+    def to_h
+      @attribute_hash.dup # dup removes the frozen flag
+    end
+
+    # Compares this object and other for equality. A `ValueStruct` is `eql?` to
+    # other when other is a `ValueStruct` and the two objects have identical
+    # fields and values.
+    #
+    # @param [Object] other the other record to compare for equality
+    # @return [Boolean] true when equal else false
+    def eql?(other)
+      other.is_a?(self.class) && @attribute_hash == other.to_h
+    end
+    alias_method :==, :eql?
+
+    # Describe the contents of this object in a string.
+    #
+    # @return [String] the string representation of this object
+    #
+    # @!visibility private
+    def inspect
+      state = @attribute_hash.to_s.gsub(/^{/, '').gsub(/}$/, '')
+      "#<#{self.class} #{state}>"
+    end
+    alias_method :to_s, :inspect
+
+    protected
+
+    # Set the value of the give field to the given value.
+    #
+    # @param [Symbol] field the field to set the value for
+    # @param [Object] value the value to set the field to
+    # @return [Object] the final value of the given field
+    #
+    # @!visibility private
+    def set_attribute(field, value)
+      @attribute_hash[field.to_sym] = value
+    end
+
+    # Check the method name and args for signatures matching potential
+    # final predicate methods. If the signature matches call the appropriate
+    # method
+    #
+    # @param [Symbol] symbol the name of the called function
+    # @param [Array] args zero or more arguments
+    # @return [Object] the result of the proxied method or the `super` call
+    #
+    # @!visibility private
+    def method_missing(symbol, *args)
+      if args.length == 0 && (match = /([^\?]+)\?$/.match(symbol))
+        set?(match[1])
+      elsif args.length == 0 && set?(symbol)
+        get(symbol)
+      else
+        super
+      end
+    end
+  end
+end

data/lib/functional/version.rb

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

data/spec/functional/final_struct_spec.rb

@@ -0,0 +1,266 @@
+require 'spec_helper'
+require 'ostruct'
+
+module Functional
+
+  describe FinalStruct do
+
+    context 'instanciation' do
+
+      specify 'with no args defines no fields' do
+        subject = FinalStruct.new
+        expect(subject.to_h).to be_empty
+      end
+
+      specify 'with a hash sets fields using has values' do
+        subject = FinalStruct.new(foo: 1, 'bar' => :two, baz: 'three')
+        expect(subject.foo).to eq 1
+        expect(subject.bar).to eq :two
+        expect(subject.baz).to eq 'three'
+      end
+
+      specify 'with a hash creates true predicates for has keys' do
+        subject = FinalStruct.new(foo: 1, 'bar' => :two, baz: 'three')
+        expect(subject.foo?).to be true
+        expect(subject.bar?).to be true
+        expect(subject.baz?).to be true
+      end
+
+      specify 'can be created from any object that responds to #to_h' do
+        clazz = Class.new do
+          def to_h; {answer: 42, harmless: 'mostly'}; end
+        end
+        struct = clazz.new
+        subject = FinalStruct.new(struct)
+        expect(subject.answer).to eq 42
+        expect(subject.harmless).to eq 'mostly'
+      end
+
+      specify 'raises an exception if given a non-hash argument' do
+        expect {
+          FinalStruct.new(:bogus)
+        }.to raise_error(ArgumentError)
+      end
+    end
+
+    context 'set fields' do
+
+      subject do
+        struct = FinalStruct.new
+        struct.foo = 42
+        struct.bar = "Don't Panic"
+        struct
+      end
+
+      specify 'have a reader which returns the value' do
+        expect(subject.foo).to eq 42
+        expect(subject.bar).to eq "Don't Panic"
+      end
+
+      specify 'have a predicate which returns true' do
+        expect(subject.foo?).to be true
+        expect(subject.bar?).to be true
+      end
+
+      specify 'raise an exception when written to again' do
+        expect {subject.foo = 0}.to raise_error(Functional::FinalityError)
+        expect {subject.bar = 0}.to raise_error(Functional::FinalityError)
+      end
+    end
+
+    context 'unset fields' do
+
+      subject { FinalStruct.new }
+
+      specify 'have a magic reader that always returns nil' do
+        expect(subject.foo).to be nil
+        expect(subject.bar).to be nil
+        expect(subject.baz).to be nil
+      end
+
+      specify 'have a magic predicate that always returns false' do
+        expect(subject.foo?).to be false
+        expect(subject.bar?).to be false
+        expect(subject.baz?).to be false
+      end
+
+      specify 'have a magic writer that sets the field' do
+        expect(subject.foo = 42).to eq 42
+        expect(subject.bar = :towel).to eq :towel
+        expect(subject.baz = "Don't Panic").to eq "Don't Panic"
+      end
+    end
+
+    context 'accessors' do
+
+      let!(:field_value_pairs) { {foo: 1, bar: :two, baz: 'three'} }
+
+      subject { FinalStruct.new(field_value_pairs) }
+
+      specify '#get returns the value of a set field' do
+        expect(subject.get(:foo)).to eq 1
+      end
+
+      specify '#get returns nil for an unset field' do
+        expect(subject.get(:bogus)).to be nil
+      end
+
+      specify '#[] is an alias for #get' do
+        expect(subject[:foo]).to eq 1
+        expect(subject[:bogus]).to be nil
+      end
+
+      specify '#set sets the value of an unset field' do
+        subject.set(:harmless, 'mostly')
+        expect(subject.harmless).to eq 'mostly'
+        expect(subject.harmless?).to be true
+      end
+
+      specify '#set raises an exception if the field has already been set' do
+        subject.set(:harmless, 'mostly')
+        expect {
+          subject.set(:harmless, 'extremely')
+        }.to raise_error(Functional::FinalityError)
+      end
+
+      specify '#[]= is an alias for set' do
+        subject[:harmless] = 'mostly'
+        expect(subject.harmless).to eq 'mostly'
+        expect {
+          subject[:harmless] = 'extremely'
+        }.to raise_error(Functional::FinalityError)
+      end
+
+      specify '#set? returns false for an unset field' do
+        expect(subject.set?(:harmless)).to be false
+      end
+
+      specify '#set? returns true for a field that has been set' do
+        subject.set(:harmless, 'mostly')
+        expect(subject.set?(:harmless)).to be true
+      end
+
+      specify '#get_or_set returns the value of a set field' do
+        subject.answer = 42
+        expect(subject.get_or_set(:answer, 100)).to eq 42
+      end
+
+      specify '#get_or_set sets the value of an unset field' do
+        subject.get_or_set(:answer, 42)
+        expect(subject.answer).to eq 42
+        expect(subject.answer?).to be true
+      end
+
+      specify '#get_or_set returns the value of a newly set field' do
+        expect(subject.get_or_set(:answer, 42)).to eq 42
+      end
+
+      specify '#fetch gets the value of a set field' do
+        subject.harmless = 'mostly'
+        expect(subject.fetch(:harmless, 'extremely')).to eq 'mostly'
+      end
+
+      specify '#fetch returns the given value when the field is unset' do
+        expect(subject.fetch(:harmless, 'extremely')).to eq 'extremely'
+      end
+
+      specify '#fetch does not set an unset field' do
+        subject.fetch(:answer, 42)
+        expect(subject.answer).to be_nil
+        expect(subject.answer?).to be false
+      end
+
+      specify '#to_h returns the key/value pairs for all set values' do
+        subject = FinalStruct.new(field_value_pairs)
+        expect(subject.to_h).to eq field_value_pairs
+      end
+
+      specify '#to_h is updated when new fields are added' do
+        subject = FinalStruct.new
+        field_value_pairs.each_pair do |field, value|
+          subject.set(field, value)
+        end
+        expect(subject.to_h).to eq field_value_pairs
+      end
+
+      specify '#each_pair returns an Enumerable when no block given' do
+        subject = FinalStruct.new(field_value_pairs)
+        expect(subject.each_pair).to be_a Enumerable
+      end
+
+      specify '#each_pair enumerates over each field/value pair' do
+        subject = FinalStruct.new(field_value_pairs)
+        result = {}
+
+        subject.each_pair do |field, value|
+          result[field] = value
+        end
+
+        expect(result).to eq field_value_pairs
+      end
+    end
+
+    context 'reflection' do
+
+      specify '#eql? returns true when both define the same fields with the same values' do
+        first = FinalStruct.new(foo: 1, 'bar' => :two, baz: 'three')
+        second = FinalStruct.new(foo: 1, 'bar' => :two, baz: 'three')
+
+        expect(first.eql?(second)).to be true
+        expect(first == second).to be true
+      end
+
+      specify '#eql? returns false when other has different fields defined' do
+        first = FinalStruct.new(foo: 1, 'bar' => :two, baz: 'three')
+        second = FinalStruct.new(foo: 1, 'bar' => :two)
+
+        expect(first.eql?(second)).to be false
+        expect(first == second).to be false
+      end
+
+      specify '#eql? returns false when other has different field values' do
+        first = FinalStruct.new(foo: 1, 'bar' => :two, baz: 'three')
+        second = FinalStruct.new(foo: 1, 'bar' => :two, baz: 3)
+
+        expect(first.eql?(second)).to be false
+        expect(first == second).to be false
+      end
+
+      specify '#eql? returns false when other is not a FinalStruct' do
+        attributes = {answer: 42, harmless: 'mostly'}
+        clazz = Class.new do
+          def to_h; {answer: 42, harmless: 'mostly'}; end
+        end
+        other = clazz.new
+        subject = FinalStruct.new(attributes)
+        expect(subject.eql?(other)).to be false
+        expect(subject == other).to be false
+      end
+
+      specify '#inspect begins with the class name' do
+        subject = FinalStruct.new(foo: 1, 'bar' => :two, baz: 'three')
+        expect(subject.inspect).to match(/^#<#{described_class}\s+/)
+      end
+
+      specify '#inspect includes all field/value pairs' do
+        field_value_pairs = {foo: 1, 'bar' => :two, baz: 'three'}
+        subject = FinalStruct.new(field_value_pairs)
+
+        field_value_pairs.each do |field, value|
+          expect(subject.inspect).to match(/:#{field}=>"?:?#{value}"?/)
+        end
+      end
+
+      specify '#to_s returns the same value as #inspect' do
+        subject = FinalStruct.new(foo: 1, 'bar' => :two, baz: 'three')
+        expect(subject.to_s).to eq subject.inspect
+      end
+
+      specify '#method_missing raises an exception for methods with unrecognized signatures' do
+        expect {
+          subject.foo(1, 2, 3)
+        }.to raise_error(NoMethodError)
+      end
+    end
+  end
+end

data/spec/functional/final_var_spec.rb

@@ -0,0 +1,169 @@
+require 'spec_helper'
+
+module Functional
+
+  describe FinalVar do
+
+    context 'instanciation' do
+
+      it 'is unset when no arguments given' do
+        expect(FinalVar.new).to_not be_set
+      end
+
+      it 'is set with the given argument' do
+        expect(FinalVar.new(41)).to be_set
+      end
+    end
+
+    context '#get' do
+
+      subject { FinalVar.new }
+
+      it 'returns nil when unset' do
+        expect(subject.get).to be nil
+      end
+
+      it 'returns the value when set' do
+        expect(FinalVar.new(42).get).to eq 42
+      end
+
+      it 'is aliased as #value' do
+        expect(subject.value).to be nil
+        subject.set(42)
+        expect(subject.value).to eq 42
+      end
+    end
+
+    context '#set' do
+
+      subject { FinalVar.new }
+
+      it 'sets the value when unset' do
+        subject.set(42)
+        expect(subject.get).to eq 42
+      end
+
+      it 'returns the new value when unset' do
+        expect(subject.set(42)).to eq 42
+      end
+
+      it 'raises an exception when already set' do
+        subject.set(42)
+        expect {
+          subject.set(42)
+        }.to raise_error(Functional::FinalityError)
+      end
+
+      it 'is aliased as #value=' do
+        subject.value = 42
+        expect(subject.get).to eq 42
+      end
+    end
+
+    context '#set?' do
+
+      it 'returns false when unset' do
+        expect(FinalVar.new).to_not be_set
+      end
+
+      it 'returns true when set' do
+        expect(FinalVar.new(42)).to be_set
+      end
+
+      it 'is aliased as value?' do
+        expect(FinalVar.new.value?).to be false
+        expect(FinalVar.new(42).value?).to be true
+      end
+    end
+
+    context '#get_or_set' do
+
+      it 'sets the value when unset' do
+        subject = FinalVar.new
+        subject.get_or_set(42)
+        expect(subject.get).to eq 42
+      end
+
+      it 'returns the new value when previously unset' do
+        subject = FinalVar.new
+        expect(subject.get_or_set(42)).to eq 42
+      end
+
+      it 'returns the current value when already set' do
+        subject = FinalVar.new(100)
+        expect(subject.get_or_set(42)).to eq 100
+      end
+    end
+
+    context '#fetch' do
+
+      it 'returns the given default value when unset' do
+        subject = FinalVar.new
+        expect(subject.fetch(42)).to eq 42
+      end
+
+      it 'does not change the current value when unset' do
+        subject = FinalVar.new
+        subject.fetch(42)
+        expect(subject.get).to be nil
+      end
+
+      it 'returns the current value when already set' do
+        subject = FinalVar.new(100)
+        expect(subject.get_or_set(42)).to eq 100
+      end
+    end
+
+    context 'reflection' do
+
+      specify '#eql? returns false when unset' do
+        expect(FinalVar.new.eql?(nil)).to be false
+        expect(FinalVar.new.eql?(42)).to be false
+        expect(FinalVar.new.eql?(FinalVar.new.value)).to be false
+      end
+
+      specify '#eql? returns false when set and the value does not match other' do
+        subject = FinalVar.new(42)
+        expect(subject.eql?(100)).to be false
+      end
+
+      specify '#eql? returns true when set and the value matches other' do
+        subject = FinalVar.new(42)
+        expect(subject.eql?(42)).to be true
+      end
+
+      specify '#eql? returns true when set and other is a FinalVar with the same value' do
+        subject = FinalVar.new(42)
+        other = FinalVar.new(42)
+        expect(subject.eql?(other)).to be true
+      end
+
+      specify 'aliases #== as #eql?' do
+        expect(FinalVar.new == nil).to be false
+        expect(FinalVar.new == 42).to be false
+        expect(FinalVar.new == FinalVar.new).to be false
+        expect(FinalVar.new(42) == 42).to be true
+        expect(FinalVar.new(42) == FinalVar.new(42)).to be true
+      end
+
+      specify '#inspect includes the word "value" and the value when set' do
+        subject = FinalVar.new(42)
+        expect(subject.inspect).to match(/value\s?=\s?42\s*>$/)
+      end
+
+      specify '#inspect include the word "unset" when unset' do
+        subject = FinalVar.new
+        expect(subject.inspect).to match(/unset\s*>$/i)
+      end
+
+      specify '#to_s returns nil as a string when unset' do
+        expect(FinalVar.new.to_s).to eq nil.to_s
+      end
+
+      specify '#to_s returns the value as a string when set' do
+        expect(FinalVar.new(42).to_s).to eq 42.to_s
+        expect(FinalVar.new('42').to_s).to eq '42'
+      end
+    end
+  end
+end