nrser 0.3.9 → 0.3.10

data/lib/nrser/types/bounded.rb

@@ -1,53 +1,116 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# ========================================================================
+
+# Project / Package
+# ------------------------------------------------------------------------
+
 require 'nrser/types/type'
+
+
+# Namespace
+# ========================================================================
+
+module  NRSER
+module  Types
+
+
+# Definitions
+# ========================================================================
+
+# Types whose members satisfy a {#min}, {#max} or both (inclusive).
+# 
+# @note
+#   Construct {Bounded} types using the {.Bounded} factory.
+# 
+class Bounded < Type
   
-module NRSER::Types
-  class Bounded < NRSER::Types::Type
-    
-    # Minimum value.
-    # 
-    # @return [Number]
-    #     
-    attr_reader :min
-    
-    
-    # Minimum value.
-    # 
-    # @return [Number]
-    # 
-    attr_reader :max
-    
-    
-    def initialize  min: nil,
-                    max: nil,
-                    **options
-      super **options
-      
-      @min = min
-      @max = max
-    end
-    
-    def test? value
-      return false if @min && value < @min
-      return false if @max && value > @max
-      true
-    end
+  # Minimum value.
+  # 
+  # @return [Number]
+  #     
+  attr_reader :min
+  
+  
+  # Minimum value.
+  # 
+  # @return [Number]
+  # 
+  attr_reader :max
+  
+  
+  def initialize  min: nil,
+                  max: nil,
+                  **options
+    super **options
     
-    def explain
-      attrs_str = ['min', 'max'].map {|name|
-        [name, instance_variable_get("@#{ name }")]
-      }.reject {|name, value|
-        value.nil?
-      }.map {|name, value|
-        "#{ name }=#{ value }"
-      }.join(', ')
-      
-      "#{ self.class.demod_name }<#{ attrs_str }>"
+    @min = min
+    @max = max
+  end
+  
+  def test? value
+    return false if @min && value < @min
+    return false if @max && value > @max
+    true
+  end
+
+  def symbolic
+    if min
+      if max
+        # has min and max, use range notation
+        "(#{ min.inspect }..#{ max.inspect })"
+      else
+        # only has min
+        "(#{ min.inspect }..)"
+        # "{ x : x #{ NRSER::Types::GEQ } #{ min } }"
+      end
+    else
+      # only has max
+      "(..#{ max.inspect })"
+      # "{ x : x #{ NRSER::Types::LEQ } #{ max } }"
     end
-    
-  end # Bounded
+  end
   
-  def_factory :bounded do |**options|
-    Bounded.new **options
+  def explain
+    attrs_str = ['min', 'max'].map {|name|
+      [name, instance_variable_get("@#{ name }")]
+    }.reject {|name, value|
+      value.nil?
+    }.map {|name, value|
+      "#{ name }=#{ value }"
+    }.join(', ')
+    
+    "#{ self.class.demod_name }<#{ attrs_str }>"
   end
-   
-end # NRSER::Types
+  
+end # Bounded
+
+
+# @!group Bounded Type Factories
+# ----------------------------------------------------------------------------
+
+#@!method self.Bounded **options
+#   Create a {Bounded} type instance that matches values between `min` and
+#   `max` (inclusive).
+#   
+#   @param [Hash] options
+#     Passed to {Type#initialize}.
+#   
+#   @return [Type]
+#   
+def_type        :Bounded,
+  parameterize: [ :min, :max ],
+&->( min: nil, max: nil, **options ) do
+  Bounded.new min: min, max: max, **options
+end # .Bounded
+
+# @!endgroup Bounded Type Factories # ****************************************
+
+
+# /Namespace
+# ========================================================================
+
+end # module Types
+end # module NRSER

data/lib/nrser/types/collections.rb

@@ -0,0 +1,119 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+
+# Requirements
+# =======================================================================
+
+# Project / Package
+# -----------------------------------------------------------------------
+require_relative './combinators'
+require_relative './responds'
+require_relative './is_a'
+
+
+# Namespace
+# ========================================================================
+
+module  NRSER
+module  Types
+
+
+# Definitions
+# =======================================================================
+
+# @!group Collection Type Factories
+# ----------------------------------------------------------------------------
+
+#@!method self.Vector **options
+#   An "array-like" {Enumerable} that responds to `#each_index` and 
+#   `#slice` / `#[]`.
+#   
+#   @param [Hash] options
+#     Passed to {Type#initialize}.
+#   
+#   @return [Type]
+#   
+def_type        :Vector,
+  aliases:      [ :array_like ],
+&->( **options ) do
+  intersection \
+    is_a( Enumerable ),
+    respond_to( :each_index ),
+    respond_to( :slice ),
+    respond_to( :[] ),
+    name: name,
+    **options
+end # .Vector
+
+
+#@!method self.Map **options
+#   A "hash-like" {Enumerable} that responds to `#each_pair` and `#[]`.
+#   
+#   @param [Hash] options
+#     Passed to {Type#initialize}.
+#   
+#   @return [Type]
+#   
+def_type        :Map,
+  aliases:      [ :hash_like, :assoc ],
+&->( **options ) do
+  intersection \
+    is_a( Enumerable ),
+    respond_to( :each_pair ),
+    respond_to( :[] ),
+    name: name,
+    **options
+end # .Map
+
+
+#@!method self.Bag **options
+#   An {Enumerable} that does **not** respond to `#each_pair`.
+#   
+#   Meant to encompass {Set}, {Array} and the like *without* {Hash} and other
+#   associative containers.
+#   
+#   Elements may or may not be indexed.
+#   
+#   @param [Hash] options
+#     Passed to {Type#initialize}.
+#   
+#   @return [Type]
+#   
+def_type        :Bag,
+&->( **options ) do
+  intersection \
+    is_a( Enumerable ),
+    self.not( respond_to( :each_pair ) ),
+    name: name,
+    **options
+end # .Bag
+
+
+#@!method self.Tree **options
+#   Either a {.Vector} or {.Map} - {Enumerable} collections with indexed
+#   elements that work with the {NRSER} "tree" functions.
+#   
+#   @param [Hash] options
+#     Passed to {Type#initialize}.
+#   
+#   @return [Type]
+#   
+def_type        :Tree,
+&->( **options ) do
+  union \
+    array_like,
+    hash_like,
+    name: name,
+    **options
+end # .Tree
+
+# @!endgroup Collection Type Factories # *************************************
+
+
+# /Namespace
+# ========================================================================
+
+end # module Types
+end # module NRSER
+

data/lib/nrser/types/combinators.rb

@@ -3,226 +3,313 @@
 
 require 'nrser/types/type'
 
-# base class for Union and Intersection which combine over a set of types.
-module NRSER::Types
+
+
+# Namespace
+# ========================================================================
+
+module  NRSER
+module  Types
+
+
+# Definitions
+# ========================================================================
+
+# Abstract base class for logically combining types to create new ones.
+# 
+# @see Union
+# @see Intersection
+# @see XOR
+# 
+class Combinator < Type
   
-  # Abstract base class for logically combining types to create new ones.
+  # The parameterized types, in the order they will be tested.
   # 
-  class Combinator < NRSER::Types::Type
-    
-    # The parametrized types, in the order they will be tested.
-    # 
-    # @return [Array<NRSER::Types::Type>]
-    # 
-    attr_reader :types
-    
-    
-    def initialize *types, **options
-      super **options
-      @types = types.map { |type| NRSER::Types.make type }
+  # @return [Array<NRSER::Types::Type>]
+  # 
+  attr_reader :types
+  
+  
+  def initialize *types, **options
+    super **options
+    @types = types.map { |type| NRSER::Types.make type }.freeze
+  end
+  
+
+  def string_format method
+    NRSER::Types::L_PAREN +
+    # ' ' + no spaces
+    @types.map { |type| type.send method }.join( self.class::JOIN_SYMBOL ) +
+    # ' ' + no spaces
+    NRSER::Types::R_PAREN
+  end
+
+
+  def default_symbolic
+    string_format( :to_s )
+  end
+
+  
+  def explain
+    return string_format( :explain )
+  end
+  
+  
+  # Parse a satisfying value from a {String} or raise a {TypeError}.
+  # 
+  # If this type has it's own `@from_s` that was provided via the `from_s:`
+  # keyword at construction, then that and **only** that is **always** used
+  # - the type will never try any of the combined types' `#from_s`.
+  # 
+  # It's considered *the* way to parse a string into a value that satisfies
+  # the type. If it fails, a {TypeError} will be raised (or any error the
+  # `@from_s` proc itself raises before we get to checking it).
+  # 
+  # If the type doesn't have it's own `@from_s`, each of the combined types'
+  # `#from_s` will be tried in sequence, and the first value that satisfies
+  # the combined type will be returned.
+  # 
+  # This is obviously much less efficient, but provides a nice automatic
+  # mechanism for parsing from strings for combined types. If none of the
+  # combined types' `#from_s` succeed (or if there are none) a {TypeError}
+  # is raised.
+  # 
+  # @param [String] s
+  #   String to parse.
+  # 
+  # @return [Object]
+  #   Object that satisfies the type.
+  # 
+  # @raise [TypeError]
+  #   See write up above.
+  # 
+  def custom_from_s string
+    # If we have an explicit `@from_s` then use that and that only.
+    unless @from_s.nil?
+      return check! @from_s.call( string )
     end
+
+    errors_by_type = {}
     
-    
-    def explain
-      if self.class::JOIN_SYMBOL
-        NRSER::Types::L_PAREN + # ' ' +
-        @types.map { |type| type.explain }.join( self.class::JOIN_SYMBOL ) +
-        # ' ' +
-        NRSER::Types::R_PAREN
+    types.each { |type|
+      if type.has_from_s?
+        begin
+          return check! type.from_s( string )
+        
+        # We want to catch any standard error here so `from_s` implementations
+        # can kinda "code without care" and if one fails we will move on to
+        # try the next.
+        rescue StandardError => error
+          errors_by_type[type] = error
+        end
       else
-        "#{ self.class.demod_name }<" +
-          @types.map { |type| type.explain }.join( ',' ) +
-        ">"
+        errors_by_type[type] = "Does not {#has_from_s?}"
       end
-    end
-    
-    
-    # Parse a satisfying value from a {String} or raise a {TypeError}.
-    # 
-    # If this type has it's own `@from_s` that was provided via the `from_s:`
-    # keyword at construction, then that and **only** that is **always** used
-    # - the type will never try any of the combined types' `#from_s`.
-    # 
-    # It's considered *the* way to parse a string into a value that satisfies
-    # the type. If it fails, a {TypeError} will be raised (or any error the
-    # `@from_s` proc itself raises before we get to checking it).
-    # 
-    # If the type doesn't have it's own `@from_s`, each of the combined types'
-    # `#from_s` will be tried in sequence, and the first value that satisfies
-    # the combined type will be returned.
-    # 
-    # This is obviously much less efficient, but provides a nice automatic
-    # mechanism for parsing from strings for combined types. If none of the
-    # combined types' `#from_s` succeed (or if there are none) a {TypeError}
-    # is raised.
-    # 
-    # @param [String] s
-    #   String to parse.
-    # 
-    # @return [Object]
-    #   Object that satisfies the type.
-    # 
-    # @raise [TypeError]
-    #   See write up above.
-    # 
-    def custom_from_s s
-      unless @from_s.nil?
-        return check @from_s.call( s )
-      end
-      
-      @types.each { |type|
-        if type.has_from_s?
-          begin
-            return check type.from_s(s)
-          rescue TypeError => e
-            # pass
-          end
-        end
-      }
-      
-      raise TypeError,
-        "none of combinator #{ self.to_s } types could convert #{ s.inspect }"
-    end
-    
+    }
     
-    # Overridden to delegate functionality to the combined types.
-    # 
-    # A combinator may attempt to parse from a string if:
-    # 
-    # 1.  It has it's own `@from_s` provided at construction.
-    # 
-    # 2.  Any of it's combined types can parse from a string.
-    # 
-    # See {#from_s} for details of how it actually happens.
-    # 
-    # @return [Boolean]
-    # 
-    def has_from_s?
-      !@from_s.nil? || @types.any? { |type| type.has_from_s? }
-    end # has_from_s
-    
-    
-    def has_from_data?
-      @types.any? { |type| type.has_from_data? }
+    # TODO  This should be "nicer"... teach {NRSER::MultipleErrors} about 
+    #       {NRSER::NicerError}?
+    raise TypeError.new \
+      "none of combinator", self.to_s, "types could convert", string.inspect,
+      string: string,
+      errors_by_type: errors_by_type
+  end
+  
+  
+  # Overridden to delegate functionality to the combined types.
+  # 
+  # A combinator may attempt to parse from a string if:
+  # 
+  # 1.  It has it's own `@from_s` provided at construction.
+  # 
+  # 2.  Any of it's combined types can parse from a string.
+  # 
+  # See {#from_s} for details of how it actually happens.
+  # 
+  # @return [Boolean]
+  # 
+  def has_from_s?
+    !@from_s.nil? || @types.any? { |type| type.has_from_s? }
+  end # has_from_s
+  
+  
+  def has_from_data?
+    @types.any? { |type| type.has_from_data? }
+  end
+  
+  
+  # Overridden to
+  def from_data data
+    unless has_from_data?
+      raise NoMethodError, "#from_data not defined"
     end
     
+    errors = []
     
-    # Overridden to
-    def from_data data
-      unless has_from_data?
-        raise NoMethodError, "#from_data not defined"
-      end
-      
-      errors = []
-      
-      types.each do |type|
-        if type.has_from_data?
-          begin
-            return check!( type.from_data data )
-          rescue StandardError => error
-            errors << error
-          end
+    types.each do |type|
+      if type.has_from_data?
+        begin
+          return check!( type.from_data data )
+        rescue StandardError => error
+          errors << error
         end
       end
-      
-      raise NRSER::MultipleErrors.new \
-        errors,
-        headline: "No type successfully loaded data"
     end
     
-    
-    # Overridden to delegate functionality to the combined types:
-    # 
-    # A combinator can convert a value to data if *any* of it's types can.
-    # 
-    # @return [Boolean]
-    # 
-    def has_to_data?
-      @types.any? { |type| type.has_to_data? }
-    end # #has_to_data
-    
-    
-    # Overridden to delegate functionality to the combined types:
-    # 
-    # The first of the combined types that responds to `#to_data` is used to
-    # dump the value.
-    # 
-    # @param [Object] value
-    #   Value of this type (though it is *not* checked).
-    # 
-    # @return [Object]
-    #   The data representation of the value.
-    # 
-    def to_data value
-      @types.each { |type|
-        if type.has_to_data?
-          return type.to_data value
-        end
-      }
-      
-      raise NoMethodError, "#to_data not defined"
-    end # #to_data
-    
-    
-    def == other
-      equal?(other) || (
-        other.class == self.class && other.types == @types
-      )
-    end
-  
-  end # class Combinator
-  
-  
-  class Union < Combinator
-    JOIN_SYMBOL = ' | ' # ' ⋁ '
-    
-    def test? value
-      @types.any? { |type| type.test value }
-    end
-  end # class Union
+    raise NRSER::MultipleErrors.new \
+      errors,
+      headline: "No type successfully loaded data"
+  end
   
   
-  # match any of the types
-  def_factory(
-    :union,
-    aliases: [:one_of, :or],
-  ) do |*types, **options|
-    Union.new *types, **options
-  end
+  # Overridden to delegate functionality to the combined types:
+  # 
+  # A combinator can convert a value to data if *any* of it's types can.
+  # 
+  # @return [Boolean]
+  # 
+  def has_to_data?
+    @types.any? { |type| type.has_to_data? }
+  end # #has_to_data
   
   
-  class Intersection < Combinator
-    JOIN_SYMBOL = ' & ' # ' ⋀ '
+  # Overridden to delegate functionality to the combined types:
+  # 
+  # The first of the combined types that responds to `#to_data` is used to
+  # dump the value.
+  # 
+  # @param [Object] value
+  #   Value of this type (though it is *not* checked).
+  # 
+  # @return [Object]
+  #   The data representation of the value.
+  # 
+  def to_data value
+    @types.each { |type|
+      if type.has_to_data?
+        return type.to_data value
+      end
+    }
     
-    def test? value
-      @types.all? { |type| type.test? value }
-    end
-  end # class Intersection
+    raise NoMethodError, "#to_data not defined"
+  end # #to_data
   
   
-  # match all of the types
-  def_factory(
-    :intersection,
-    aliases: [:all_of, :and],
-  ) do |*types, **options|
-    Intersection.new *types, **options
+  def == other
+    equal?(other) || (
+      other.class == self.class && other.types == @types
+    )
   end
+
+end # class Combinator *****************************************************
+
+
+# Concrete Implementation Classes
+# ----------------------------------------------------------------------------
+
+
+# Union combinator. (`union`, `one_of`, `or`, `|`).
+# 
+class Union < Combinator
+  JOIN_SYMBOL = ' | ' # ' ⋁ '
   
-  
-  class XOR < Combinator
-    JOIN_SYMBOL = ' ⊕ '
-    
-    def test? value
-      @types.count { |type| type === value } == 1
-    end
+  def test? value
+    @types.any? { |type| type.test value }
   end
+end # class Union
+
+
+# Intersection combinator (`intersection`, `all_of`, `and`, `&).
+# 
+class Intersection < Combinator
+  JOIN_SYMBOL = ' & ' # ' ⋀ '
   
-  
-  def_factory(
-    :xor,
-    aliases: [ :exclusive_or, :only_one_of ],
-  ) do |*types, **options|
-    XOR.new *types, **options
+  def test? value
+    @types.all? { |type| type.test? value }
   end
+end # class Intersection
+
+
+# XOR combinator - Exclusive Or (`xor`).
+# 
+class XOR < Combinator
+  JOIN_SYMBOL = ' ⊕ '
   
-end # NRSER::Types
+  def test? value
+    @types.count { |type| type === value } == 1
+  end
+end
+
+
+# @!group Combinator Type Factories
+# ----------------------------------------------------------------------------
+
+
+#@!method self.Union *types, **options
+#   Match any of the types.
+#   
+#   @param [Type | Object] types
+#     Types to combine over. Objects that are not {Type} instances will me
+#     made into them via {.make}.
+#   
+#   @param [Hash] options
+#     Passed to {Type#initialize}.
+#   
+#   @return [Type]
+#   
+def_type        :Union,
+  aliases:      [ :one_of, :or ],
+  parameterize: [ :types ],
+&->( *types, **options ) do
+  Union.new *types, **options
+end # .Union
+
+
+#@!method self.Intersection *types, **options
+#   Match all of the types
+#   
+#   @param [Type | Object] types
+#     Types to combine over. Objects that are not {Type} instances will me
+#     made into them via {.make}.
+#   
+#   @param [Hash] options
+#     Passed to {Type#initialize}.
+#   
+#   @return [Type]
+#   
+def_type        :Intersection,
+  aliases:      [ :all_of, :and ],
+  parameterize: [ :types ],
+&->( *types, **options ) do
+  Intersection.new *types, **options
+end # .Intersection
+
+
+#@!method self.XOR *types, **options
+#   Match one of the types only.
+#   
+#   @param [Type | Object] types
+#     Types to combine over. Objects that are not {Type} instances will me
+#     made into them via {.make}.
+#   
+#   @param [Hash] options
+#     Passed to {Type#initialize}.
+#   
+#   @return [Type]
+#   
+def_type        :XOR,
+  aliases:      [ :exclusive_or, :only_one_of ],
+  parameterize: [ :types ],
+&->( *types, **options ) do
+  XOR.new *types, **options
+end # .XOR
+
+# @!endgroup Combinator Type Factories # *************************************
+
+
+# /Namespace
+# ========================================================================
+
+end # module Types
+end # module NRSER
+