nrser 0.2.2 → 0.3.0

data/lib/nrser/types/type.rb

@@ -1,8 +1,21 @@
-# Refinements
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
 # =======================================================================
 
-require 'nrser/refinements'
-using NRSER
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+# Just require the errors here so we don't need to do it everywhere
+require_relative './errors/check_error'
+require_relative './errors/from_string_error'
 
 
 # Definitions
@@ -10,10 +23,6 @@ using NRSER
 
 module NRSER::Types
   class Type
-    def self.short_name
-      name.split('::').last
-    end
-    
     
     # Constructor
     # =====================================================================
@@ -82,88 +91,183 @@ module NRSER::Types
     end # #initialize
     
     
+    # Instance Methods
+    # ========================================================================
+    
+    # @!group Display Instance Methods
+    # ------------------------------------------------------------------------
+    
+    # What this type likes to be called (and displayed as by default).
+    # 
+    # Custom names can be provided when constructing most types via the
+    # `name:` keyword, which allows thinking about composite and complicated
+    # types in simpler and application-specific terms.
+    # 
+    # Realizing subclasses **should not** override this method - they should
+    # pass a `name:` keyword up to {#initialize}, which sets the `@name`
+    # instance variable that is then used here.
+    # 
+    # If no name is provided to {#initialize}, this method will fall back to
+    # {#explain}.
+    # 
+    # @return [String]
+    # 
     def name
-      @name || default_name
+      @name || explain
     end
     
-    def default_name
-      self.class.short_name
+    
+    # A string that gives our best concise description of the type's logic,
+    # in particular exposing any composite types that it's made up of.
+    # 
+    # Used as the {#name} when a custom one is not provided.
+    # 
+    # Meant for inline display, so the result *should not* contain newlines.
+    # 
+    # Realizing subclasses **should** override this method, as this
+    # implementation only returns the class' name (and just the last segment,
+    # for brevity's sake).
+    # 
+    # @example Base implementation is not very interesting
+    #   MyType = Class.new NRSER::Types::Type
+    #   my_type = MyType.new
+    #   my_type.explain
+    #   # => "MyType"
+    # 
+    # @return [String]
+    # 
+    def explain
+      self.class.demod_name
     end
     
+    # @!endgroup Display Instance Methods # **********************************
+    
+    
+    # @!group Validation Instance Methods
+    # ------------------------------------------------------------------------
+    # 
+    # The core of what a type does.
+    # 
     
     # See if a value satisfies the type.
     # 
+    # Realizing classes **must** implement this method.
+    # 
+    # This implementation just defines the API; it always raises
+    # {NRSER::AbstractMethodError}.
+    # 
     # @param [Object] value
     #   Value to test for type satisfaction.
     # 
     # @return [Boolean]
     #   `true` if the `value` satisfies the type.
     # 
-    def test value
-      raise NotImplementedError
+    def test? value
+      raise NRSER::AbstractMethodError.new( self, __method__ )
     end
     
+    # Old name for {#test?}.
+    # 
+    # @deprecated
+    # 
+    # @param  (see #test?)
+    # @return (see #test?)
+    # @raise  (see #test?)
+    # 
+    def test value; test? value; end
     
-    def check value, &make_fail_message
+    
+    # Check that a `value` satisfies the type.
+    # 
+    # @see #test?
+    # 
+    # @return [Object]
+    #   The value itself.
+    # 
+    # @raise [NRSER::Types::CheckError]
+    #   If the value does not satisfy this type.
+    # 
+    def check! value, &details
       # success case
-      return value if test value
-      
-      msg = if make_fail_message
-        make_fail_message.call type: self, value: value
-      else
-        NRSER.squish <<-END
-          value #{ value.inspect } failed check #{ self.to_s }
-        END
-      end
+      return value if test? value
       
-      raise TypeError.new msg
+      raise NRSER::Types::CheckError.new \
+        value: value,
+        type: self,
+        details: details
     end
     
+    # Old name for {#check!} without the bang.
+    def check *args, &block; check! *args, &block; end
+    
+    # @!endgroup Validation Instance Methods # *******************************
     
-    # Overridden to customize behavior for the {#from_s} and {#to_data}
-    # methods - those methods are always defined, but we have {#respond_to?}
-    # return `false` if they lack the underlying instance variables needed
-    # to execute.
+    
+    # @!group Loading Values Instance Methods
+    # ------------------------------------------------------------------------
     # 
-    # @example
-    #   t1 = t.where { |value| true }
-    #   t1.respond_to? :from_s
-    #   # => false
-    #   
-    #   t2 = t.where( from_s: ->(s){ s.split ',' } ) { |value| true }
-    #   t2.respond_to? :from_s
-    #   # => true
+    # Types include facilities for loading values from representations and
+    # encodings.
     # 
-    # @param [Symbol | String] name
-    #   Method name to ask about.
+    # This was initially driven by the desire to use types to
+    # declare CLI parameter schemas, as way to dispatch with the often
+    # limited and arbitrary support most "CLI frameworks" have for declaring
+    # option types - things like "you can have an integer, and you can
+    # have an array, but you can't have an array of integers".
     # 
-    # @param [Boolean] include_all
-    #   IDK, part of Ruby API that is passed up to `super`.
+    # By using compossible types that can load values from strings we get a
+    # system where you can easily declare whatever complex and granular types
+    # you desire and have the machine automatically load and validate them,
+    # as well as provide reasonable generated feedback when something doesn't
+    # meet expectations, which has worked out quite well so far start to cut
+    # down the amount of repetitive and error-prone "did I get what I need?
+    # No, did I get exactly what I need?" bullshit in receiving data.
+    # 
+    # This approach is now being expanded to "data" - an ill-formed concept
+    # I've been brewing of "reasonable common and portable data
+    # representation" and the {NRSER::Props} system, which has been coming
+    # along as well.
+    # 
+    
+    # Test if the type knows how to load values from strings.
+    # 
+    # Looks for the `@from_s` instance variable or a `#custom_from_s`
+    # method.
+    # 
+    # @note
+    #   When this method returns `true` it simply indicates that some method
+    #   of loading from strings exists - the load itself can of course still
+    #   fail.
+    # 
+    # Realizing classes should only need to override this method to limited or
+    # expand the scope relative to parameterized types.
     # 
     # @return [Boolean]
     # 
-    def respond_to? name, include_all = false
-      if name == :from_s || name == 'from_s'
-        has_from_s?
-      elsif name == :to_data || name == 'to_data'
-        has_to_data?
-      else
-        super name, include_all
-      end
-    end # #respond_to?
+    def has_from_s?
+      !@from_s.nil? ||
+        # Need the `true` second arg to include protected methods
+        respond_to?( :custom_from_s, true )
+    end
     
     
-    # Load a value of this type from a string representation by passing `s`
-    # to the {@from_s} {Proc}.
+    # Load a value of this type from a string representation by passing
+    # `string` to the {@from_s} {Proc}.
     # 
-    # Checks the value {@from_s} returns with {#check} before returning it, so
+    # Checks the value {@from_s} returns with {#check!} before returning it, so
     # you know it satisfies this type.
     # 
-    # @param [String] s
+    # Realizing classes **should not** need to override this - they can define
+    # a `#custom_from_s` instance method for it to use, allowing individual
+    # types to still override that by providing a `from_s:` proc keyword
+    # arg at construction. This also lets them avoid checking the returned
+    # value, since we do so here.
+    # 
+    # @param [String] string
     #   String representation.
     # 
     # @return [Object]
-    #   Value that has passed {#check}.
+    #   Value that has passed {#check!}.
     # 
     # @raise [NoMethodError]
     #   If this type doesn't know how to load values from strings.
@@ -180,34 +284,67 @@ module NRSER::Types
     # @raise [TypeError]
     #   If the value loaded does not pass {#check}.
     # 
-    def from_s s
-      if @from_s.nil?
-        raise NoMethodError, "#from_s not defined"
+    def from_s string
+      unless has_from_s?
+        raise NoMethodError, "#from_s not defined for type #{ name }"
       end
       
-      check @from_s.call( s )
-    end
-    
-    
-    def from_data data
-      if @from_data.nil?
-        raise NoMethodError, "#from_data not defined"
+      value = if @from_s
+        @from_s.call string
+      else
+        custom_from_s string
       end
       
-      check @from_data.call( data )
+      check! value
     end
     
     
-    # Test if the type knows how to load values from strings.
+    # Test if the type can load values from "data" - basic values and
+    # collections like {Array} and {Hash} forming tree-like structures.
     # 
-    # If this method returns `true`, then we expect {#from_s} to succeed.
+    # Realizing classes *may* need to override this to limited or expand
+    # responses relative to parameterized types.
     # 
     # @return [Boolean]
     # 
-    def has_from_s?
-      ! @from_s.nil?
+    def has_from_data?
+      !@from_data.nil? ||
+        # Need the `true` second arg to include protected methods
+        respond_to?( :custom_from_data, true )
+    end
+    
+    
+    # Try to load a value from "data" - basic values and
+    # collections like {Array} and {Hash} forming tree-like structures.
+    # 
+    # @param [*] data
+    #   Data to try to load from.
+    # 
+    # @raise [NoMethodError]
+    #   If {#has_from_data?} returns `false`.
+    # 
+    # @raise [NRSER::Types::CheckError]
+    #   If the load result does not satisfy the type (see {#check!}).
+    # 
+    def from_data data
+      unless has_from_data?
+        raise NoMethodError, "#from_data not defined"
+      end
+      
+      value = if @from_data
+        @from_data.call data
+      else
+        custom_from_data data
+      end
+      
+      check! value
     end
     
+    # @!endgroup Loading Values Instance Methods # ***************************
+    
+    
+    # @!group Dumping Values Instance Methods
+    # ------------------------------------------------------------------------
     
     # Test if the type has custom information about how to convert it's values
     # into "data" - structures and values suitable for transportation and
@@ -222,11 +359,6 @@ module NRSER::Types
     end # #has_to_data?
     
     
-    def has_from_data?
-      ! @from_data.nil?
-    end
-    
-    
     # Dumps a value of this type to "data" - structures and values suitable
     # for transport and storage, such as dumping to JSON or YAML, etc.
     # 
@@ -244,22 +376,67 @@ module NRSER::Types
       @to_data.call value
     end # #to_data
     
+    # @!endgroup Dumping Values Instance Methods # ***************************
     
-    # Language Inter-Op
-    # =====================================================================
     
+    # @!group Language Integration Instance Methods
+    # ------------------------------------------------------------------------
     
+    # Proxies to {#name}.
+    # 
     # @return [String]
-    #   a brief string description of the type - just it's {#name} surrounded
-    #   by some back-ticks to make it easy to see where it starts and stops.
     # 
-    def to_s
-      "{ x ∈ #{ name } }"
+    def to_s; name; end
+    
+    
+    # Hook into Ruby's *case subsumption* operator to allow usage in `case`
+    # statements! Forwards to {#test?}.
+    # 
+    # @param value (see #test?)
+    # @return (see #test?)
+    #   
+    def === value
+      test? value
     end
     
     
-    # Inspecting
-    # ---------------------------------------------------------------------
+    # Overridden to customize behavior for the {#from_s}, {#from_data} and
+    # {#to_data} methods - those methods are always defined, but we have
+    # {#respond_to?} return `false` if they lack the underlying instance
+    # variables needed to execute.
+    # 
+    # @example
+    #   t1 = t.where { |value| true }
+    #   t1.respond_to? :from_s
+    #   # => false
+    #   
+    #   t2 = t.where( from_s: ->(s){ s.split ',' } ) { |value| true }
+    #   t2.respond_to? :from_s
+    #   # => true
+    # 
+    # @param [Symbol | String] name
+    #   Method name to ask about.
+    # 
+    # @param [Boolean] include_all
+    #   IDK, part of Ruby API that is passed up to `super`.
+    # 
+    # @return [Boolean]
+    # 
+    def respond_to? name, include_all = false
+      case name.to_sym
+      when :from_s
+        has_from_s?
+      when :from_data
+        has_from_data?
+      when :to_data
+        has_to_data?
+      else
+        super name, include_all
+      end
+    end # #respond_to?
+    
+    
+    ### Inspecting
     # 
     # Due to their combinatoric nature, types can quickly become large data
     # hierarchies, and the built-in {#inspect} will produce a massive dump
@@ -270,24 +447,98 @@ module NRSER::Types
     # 
     # As a solution, we alias the built-in `#inspect` as {#builtin_inspect},
     # so it's available in situations where you really want all those gory
-    # details, and point {#inspect} to {#to_s}.
+    # details, and point {#inspect} to {#explain}.
     # 
     
     alias_method :builtin_inspect, :inspect
-    alias_method :inspect, :to_s
+    def inspect
+      name = self.name
+      explain = self.explain
+      
+      if name == explain
+        explain
+      else
+        "#{ name } := #{ explain }"
+      end
+    end
     
+    # @!endgroup Language Integration Instance Methods # *********************
     
-    # Hook into Ruby's *case subsumption* operator to allow usage in `case`
-    # statements!
+    
+    # @!group Derivation Instance Methods
+    # ------------------------------------------------------------------------
     # 
-    # TODO  Want to switch {NRSER::Types.match} over to use `===`!
+    # Methods for deriving new types from `self`.
     # 
-    # @param value (see #test)
-    # @return (see #test)
-    #   
-    def === value
-      test value
+    
+    # Return a *union* type satisfied by values that satisfy either `self`
+    # *or* and of `others`.
+    # 
+    # @param [*] other
+    #   Values passed through {NRSER::Types.make} to create the other types.
+    # 
+    # @return [NRSER::Types::Union]
+    # 
+    def union *others
+      require_relative './combinators'
+      
+      NRSER::Types.union self, *others
+    end # #union
+    
+    alias_method :|, :union
+    alias_method :or, :union
+    
+    
+    # Return an *intersection* type satisfied by values that satisfy both
+    # `self` *and* all of `others`.
+    # 
+    # @param [Array] *others
+    #   Values passed through {NRSER::Types.make} to create the other types.
+    # 
+    # @return [NRSER::Types::Intersection]
+    # 
+    def intersection *others
+      require_relative './combinators'
+      
+      NRSER::Types.intersection self, *others
+    end # #intersection
+    
+    alias_method :&, :intersection
+    alias_method :and, :intersection
+    
+    
+    # Return an *exclusive or* type satisfied by values that satisfy either
+    # `self` *or* `other` *but not both*.
+    # 
+    # @param [*] other
+    #   Value passed through {NRSER::Types.make} to create the other type.
+    # 
+    # @return [NRSER::Types::Intersection]
+    # 
+    def xor *others
+      require_relative './combinators'
+      
+      NRSER::Types.xor self, *others
+    end # #^
+    
+    alias_method :^, :xor
+    
+    
+    # Return a "negation" type satisfied by all values that do *not* satisfy
+    # `self`.
+    # 
+    # @return [NRSER::Types::Not]
+    # 
+    def not
+      require_relative './not'
+      
+      NRSER::Types.not self
     end
     
+    alias_method :~, :not
+    
+    # @!endgroup Derivation Instance Methods # *******************************
+    
+    
   end # Type
 end # NRSER::Types

data/lib/nrser/types/when.rb

@@ -1,24 +1,13 @@
+# encoding: UTF-8
 # frozen_string_literal: true
 
 # Requirements
 # =======================================================================
 
-# Stdlib
-# -----------------------------------------------------------------------
-
-# Deps
-# -----------------------------------------------------------------------
-
 # Project / Package
 # -----------------------------------------------------------------------
 
-
-# Refinements
-# =======================================================================
-
-
-# Declarations
-# =======================================================================
+require_relative './type'
 
 
 # Definitions
@@ -26,9 +15,31 @@
 
 module NRSER::Types
   
+  # Wraps an object as a type, using Ruby's "case equality" `===` to test
+  # membership (like a `when` clause in a `case` expression).
+  # 
+  # Deals with some data loading too.
+  # 
+  # @note
+  #   This was kinda hacked in when my idiot-ass figured out that all this
+  #   types BS could fit in real well with Ruby's `===`, allowing types to
+  #   be used in `when` clauses.
+  #   
+  #   Previously, {NRSER::Types.make} used to see if something was a module,
+  #   and turn those into `is_a` types, and turn everything else into
+  #   `is`, but this kind of sucked for a bunch of reasons I don't totally
+  #   remember.
+  #   
+  #   Now, if a value is not a special case (like `nil`) or already a type,
+  #   {NRSER::Types.make} turns it into a {When}.
+  #   
+  #   {When} instances are totally Ruby-centric, and are thus mostly to
+  #   support in-runtime testing - you wouldn't want a {When} type to
+  #   be part of an API schema or something - but they're really nice for
+  #   the internal stuff.
+  # 
   class When < Type
     
-    
     # The wrapped {Object} whose `#===` will be used to test membership.
     # 
     # @return [Object]
@@ -49,15 +60,26 @@ module NRSER::Types
     # Instance Methods
     # ======================================================================
     
-    def test value
+    def test? value
       @object === value
     end
     
     
-    def default_name
-      @object.to_s
+    def explain
+      @object.inspect
+    end
+    
+    
+    def has_from_s?
+      @from_s || object.respond_to?( :from_s )
     end
     
+    
+    def custom_from_s string
+      object.from_s string
+    end
+    
+    
     # If {#object} responds to `#from_data`, call that and check results.
     # 
     # Otherwise, forward up to {NRSER::Types::Type#from_data}.
@@ -95,7 +117,7 @@ module NRSER::Types
   end # class When
   
   
-  def self.when value, **options
+  def_factory :when do |value, **options|
     When.new value, **options
   end