nrser 0.3.9 → 0.3.10

data/lib/nrser/types/when.rb

@@ -10,115 +10,140 @@
 require_relative './type'
 
 
+# Namespace
+# ========================================================================
+
+module  NRSER
+module  Types
+
+
 # Definitions
 # =======================================================================
 
-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, {.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,
+#   {.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]
+  #     
+  attr_reader :object
+  
+  
+  # Constructor
+  # ======================================================================
+  
+  # Instantiate a new `::When`.
+  def initialize object, **options
+    super **options
+    @object = object
+  end # #initialize
+  
+  
+  # Instance Methods
+  # ======================================================================
+  
+  def test? value
+    @object === value
+  end
+  
+  
+  def explain
+    @object.inspect
+  end
+  
+  
+  def has_from_s?
+    @from_s || object.respond_to?( :from_s )
+  end
+  
   
-  # Wraps an object as a type, using Ruby's "case equality" `===` to test
-  # membership (like a `when` clause in a `case` expression).
+  def custom_from_s string
+    object.from_s string
+  end
+  
+  
+  # If {#object} responds to `#from_data`, call that and check results.
   # 
-  # Deals with some data loading too.
+  # Otherwise, forward up to {::Type#from_data}.
   # 
-  # @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.
+  # @param [Object] data
+  #   Data to create the value from that will satisfy the type.
   # 
-  class When < Type
-    
-    # The wrapped {Object} whose `#===` will be used to test membership.
-    # 
-    # @return [Object]
-    #     
-    attr_reader :object
-    
-    
-    # Constructor
-    # ======================================================================
-    
-    # Instantiate a new `NRSER::Types::When`.
-    def initialize object, **options
-      super **options
-      @object = object
-    end # #initialize
-    
-    
-    # Instance Methods
-    # ======================================================================
-    
-    def test? value
-      @object === value
-    end
-    
-    
-    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}.
-    # 
-    # @param [Object] data
-    #   Data to create the value from that will satisfy the type.
-    # 
-    # @return [Object]
-    #   Instance of {#object}.
-    # 
-    def from_data data
-      if @from_data.nil?
-        if @object.respond_to? :from_data
-          check @object.from_data( data )
-        else
-          super data
-        end
+  # @return [Object]
+  #   Instance of {#object}.
+  # 
+  def from_data data
+    if @from_data.nil?
+      if @object.respond_to? :from_data
+        check @object.from_data( data )
       else
-        @from_data.call data
+        super data
       end
+    else
+      @from_data.call data
     end
-    
-    
-    def has_from_data?
-      @from_data || @object.respond_to?( :from_data )
-    end
-    
-    
-    def == other
-      equal?( other ) ||
-      ( self.class == other.class &&
-        self.object == other.object )
-    end
-    
-  end # class When
+  end
   
   
-  def_factory :when do |value, **options|
-    When.new value, **options
+  def has_from_data?
+    @from_data || @object.respond_to?( :from_data )
   end
   
-end # module NRSER::Types
+  
+  def == other
+    equal?( other ) ||
+    ( self.class == other.class &&
+      self.object == other.object )
+  end
+  
+end # class When
+
+
+#@!method self.When value, **options
+#   Get a type parameterizing a `value` whose members are all objects `obj`
+#   such that `value === obj` ("case equality").
+#   
+#   @param [Object] value
+#     Any object.
+#   
+#   @param [Hash] options
+#     Passed to {Type#initialize}.
+#   
+#   @return [When]
+#   
+def_type          :When,
+  parameterize:   :value,
+  default_name:   false,
+&->( value, **options ) do
+  When.new value, **options
+end # .When
+
+
+# /Namespace
+# ========================================================================
+
+end # module  Types
+end # module  NRSER

data/lib/nrser/types/where.rb

@@ -1,107 +1,198 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
+require 'nrser/core_ext/method'
+
 require_relative './type'
 
-module NRSER::Types
+
+# Namespace
+# ========================================================================
+
+module  NRSER
+module  Types
+
+
+# Definitions
+# ========================================================================
+
+# {Where} instances are predicate functions¹ as a type.
+# 
+# They have a {#predicate} block, and {#test?} calls it with values and
+# returns the boolean of the result (double-bangs it `!!`).
+# 
+# Super simple, right? And easy! Why don't we just use these things all over
+# the place?
+# 
+# If you're been around the programing block a few times, you probably saw
+# this coming a mile away: you should avoid using them.
+# 
+# Yeah, sorry. Here's the reasons:
+# 
+# 1.  They're **opaque** - it's hard to see inside a {Proc}... even if you
+#     got the source code (which seems like it requires gems and involves
+#     some amount of hackery), that wouldn't really give you the whole
+#     picture because you need to look at the binding as well... Ruby
+#     procs capture their entire environment.
+#     
+#     Essentially, they suck to easily and/or comprehensively communicate
+#     what they hell they do.
+#     
+# 2.  Like {When}, they're totally Ruby-centric... we can't really serialize
+#     them and pass them off anywhere, so they're shitty for APIs and
+#     property types and stuff that you may want or need to expose outside
+#     the runtime.
+#     
+#     In this sense they're ok as implementations of types like {.file_path}
+#     that represent an *idea* to be communicated to the outside world,
+#     where each system that handles that idea will need to have it's own
+#     implementation of it.
+#     
+#     Lit addresses a lot of this with serializable functions, but that's
+#     nowhere near ready to rock, and support for it would probably be
+#     added along side {Where}, not in place of it (since {Where} is
+#     probably still going to be used and useful).
+# 
+# So please be aware of those, and be reasonable about your {Where}s.
+# 
+# > ¹ I say *functions*, because they really *should* be functions (same
+# > input always gets same output, pure, etc.).
+# >
+# > Yeah, there's not much stopping you from making them state-based or
+# > random or whatever, but please don't do that shit unless you've really
+# > thought it through. And if you still do, please write me and tell me
+# > what you thought and why it's a reasonable idea and I'll update this.
+# 
+class Where < Type
   
-  # {Where} instances are predicate functions¹ as a type.
-  # 
-  # They have a {#predicate} block, and {#test?} calls it with values and
-  # returns the boolean of the result (double-bangs it `!!`).
-  # 
-  # Super simple, right? And easy! Why don't we just use these things all over
-  # the place?
-  # 
-  # If you're been around the programing block a few times, you probably saw
-  # this coming a mile away: you should avoid using them.
-  # 
-  # Yeah, sorry. Here's the reasons:
-  # 
-  # 1.  They're **opaque** - it's hard to see inside a {Proc}... even if you
-  #     got the source code (which seems like it requires gems and involves
-  #     some amount of hackery), that wouldn't really give you the whole
-  #     picture because you need to look at the binding as well... Ruby
-  #     procs capture their entire environment.
-  #     
-  #     Essentially, they suck to easily and/or comprehensively communicate
-  #     what they hell they do.
-  #     
-  # 2.  Like {When}, they're totally Ruby-centric... we can't really serialize
-  #     them and pass them off anywhere, so they're shitty for APIs and
-  #     property types and stuff that you may want or need to expose outside
-  #     the runtime.
-  #     
-  #     In this sense they're ok as implementations of types like {.file_path}
-  #     that represent an *idea* to be communicated to the outside world,
-  #     where each system that handles that idea will need to have it's own
-  #     implementation of it.
-  #     
-  #     Lit addresses a lot of this with serializable functions, but that's
-  #     nowhere near ready to rock, and support for it would probably be
-  #     added along side {Where}, not in place of it (since {Where} is
-  #     probably still going to be used and useful).
-  # 
-  # So please be aware of those, and be reasonable about your {Where}s.
-  # 
-  # > ¹ I say *functions*, because they really *should* be functions (same
-  # > input always gets same output, pure, etc.).
-  # >
-  # > Yeah, there's not much stopping you from making them state-based or
-  # > random or whatever, but please don't do that shit unless you've really
-  # > thought it through. And if you still do, please write me and tell me
-  # > what you thought and why it's a reasonable idea and I'll update this.
-  # 
-  class Where < NRSER::Types::Type
-    
-    # Predicate {Proc} used to test value for membership.
-    # 
-    # @return [Proc<(V) => Boolean>]
-    #   Really, we double-bang (`!!`) whatever the predicate returns to
-    #   get the result in {#test?}, but you get the idea... the response will
-    #   be evaluated on its truthiness.
-    # 
-    attr_reader :predicate
-    
-    
-    # Make a new {Where}.
-    # 
-    # @param [Proc<(V) => Boolean>] &predicate
-    #   See {#predicate}.
-    # 
-    # @param **options (see NRSER::Types::Type#initialize)
-    # 
-    def initialize **options, &predicate
-      super **options
+  # Predicate {Proc} used to test value for membership.
+  # 
+  # @return [Proc<(V) => Boolean>]
+  #   Really, we double-bang (`!!`) whatever the predicate returns to
+  #   get the result in {#test?}, but you get the idea... the response will
+  #   be evaluated on its truthiness.
+  # 
+  attr_reader :predicate
+  
+  
+  # Make a new {Where}.
+  # 
+  # @note
+  #   Documentation and examples are indented to illustrate behavior and
+  #   aid in development. Please use the factory method {Types.where} to
+  #   create instances - they allow us to easily improve and optimize 
+  # 
+  # 
+  # @overload initialize method, **options
+  #   
+  #   This is the preferred form, where a bound method provide the membership
+  #   predicate.
+  #   
+  #   Class or module methods make the most sense, though this is not enforced.
+  #   
+  #   @example Create a {Type} that tests if a path is a file
+  #     type = Where.new File.method( :file? )
+  # 
+  #   @param [Method<(Object)=>Boolean>] method
+  #     Arity 1 bound method that will be used to decide membership (if it 
+  #     responds truthy then the argument is a member of the type).
+  #   
+  #   @param [Hash] options
+  #     Additional options that will be passed up to {Type#initialize}.
+  # 
+  # 
+  # @overload initialize **options, &block
+  #   
+  #   This form should be used sparingly - please use a bound class or module
+  #   {Method} instead of an opaque `&block` for the predicate.
+  #   
+  #   it exists mostly for legacy reasons, and for the 
+  #   
+  #   @param [String] name
+  #     In this form, a `name` is required because it is not usually possible 
+  #     to extract any descriptive information from the `&block`.
+  # 
+  #   @param [Hash] options
+  #     Additional options that will be passed up to {Type#initialize}.
+  # 
+  #   @param [Proc<(Object)=>Boolean>] block
+  #     Arity 1 {Proc} that will be used to decide membership (if it responds 
+  #     truthy then the argument is a member of the type).
+  #   
+  # 
+  def initialize method = nil, **options, &block
+    # Check up on what we got
+
+    if method && block
+      raise NRSER::ArgumentError.new \
+        "Can't supply both method", method, "(first arg)",
+        "and &block", block
       
-      unless predicate.arity == 1
-        raise NRSER::ArgumentError.new \
-          "Predicate block must have arity 1",
-          predicate: predicate,
-          options: options
-      end
+    elsif !method && !block
+      raise NRSER::ArgumentError.new \
+        "Must provide either a Method<(Object)=>Boolean> as the first argument",
+        "*or* a Proc<(Object)=>Boolean> as the block"
       
-      @predicate = predicate
     end
+
+    @predicate = method || block
     
-    
-    # Test a value for membership.
-    # 
-    # @param  (see NRSER::Types::Type#test?)
-    # @return (see NRSER::Types::Type#test?)
-    # @raise  (see NRSER::Types::Type#test?)
-    # 
-    def test? value
-      !!@predicate.call(value)
+    unless predicate.arity == 1
+      raise NRSER::ArgumentError.new \
+        "{NRSER::Types::Where} predicates must have arity 1",
+        predicate: predicate,
+        arity: predicate.arity,
+        options: options
     end
-    
-  end # class Where
+
+    unless options[:name]
+      if predicate.is_a?( Method )
+        options[:name] = predicate.full_name
+      else
+        raise NRSER::ArgumentError.new \
+          "`name:` keyword argument is required when creating {Where}",
+          "from `&block` predicates."
+      end
+    end
+
+    super **options
+
+  end
   
   
-  # Get a type based on a predicate.
+  # Test a value for membership.
+  # 
+  # @param  (see Type#test?)
+  # @return (see Type#test?)
+  # @raise  (see Type#test?)
   # 
-  def_factory :where do |**options, &predicate|
-    Where.new **options, &predicate
+  def test? value
+    !!@predicate.call( value )
+  end
+
+
+  # A string that is supposed to give our best concise description of the type.
+  # 
+  # {Where} sucks because we can't really do much here.
+  # 
+  # @return [String]
+  # 
+  def explain
+    "#{ self.class.demod_name }<#{ @name }>"
   end
   
-end # NRSER::Types
+end # class Where ************************************************************
+
+
+# Get a type based on a predicate.
+# 
+def_type :Where, &->( *args, &block ) do
+  Where.new *args, &block
+end
+
+
+# /Namespace
+# ========================================================================
+
+end # module Types
+end # module NRSER