nrser 0.2.2 → 0.3.0

data/lib/nrser/types/errors/check_error.rb

@@ -0,0 +1,86 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Project / Package
+# -----------------------------------------------------------------------
+require 'nrser/errors/nicer_error'
+
+
+# Definitions
+# =======================================================================
+
+# This error (or a subclass) is thrown when types fail to
+# {NRSER::Types::Type.check!}.
+# 
+class NRSER::Types::CheckError < ::TypeError
+  
+  # Mixins
+  # ==========================================================================
+  
+  include NRSER::NicerError
+  
+  
+  # Attributes
+  # ========================================================================
+  
+  # The type that was checked against.
+  # 
+  # @return [NRSER::Types::Type]
+  #     
+  attr_reader :type
+  
+  
+  # The value that failed the type check.
+  # 
+  # @return [*]
+  #     
+  attr_reader :value
+  
+  
+  # Constructor
+  # ========================================================================
+  
+  # Construct a `NicerError`.
+  # 
+  # @param [*] value:
+  #   The {#value} that failed the check.
+  # 
+  # @param [NRSER::Types::Type] type:
+  #   The type that was checked.
+  # 
+  # @param details: (see NRSER::NicerError#initialize)
+  # 
+  # @param **kwds
+  #   See {NRSER::NicerError#initialize}
+  # 
+  def initialize *message, value:, type:, details: nil, **kwds
+    @value = value
+    @type = type
+    
+    if details.is_a?( Proc ) && details.arity != 0
+      orig_details = details
+      details = -> { orig_details.call type: type, value: value }
+    end
+    
+    super \
+      *message,
+      type: type,
+      value: value,
+      details: details,
+      **kwds
+  end
+  
+  
+  # Build default message when none provided.
+  # 
+  # @return [String]
+  # 
+  def default_message
+    ["Value", value.inspect, "failed check for type", type.name]
+  end # #default_message
+  
+  
+end # class NRSER::Types::TypeError

data/lib/nrser/types/errors/from_string_error.rb

@@ -0,0 +1,82 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Project / Package
+# -----------------------------------------------------------------------
+require 'nrser/errors/nicer_error'
+
+
+# Definitions
+# =======================================================================
+
+# Raised when a {NRSER::Types::Type} fails to load a value from a {String}
+# (via it's `#from_s` method).
+# 
+# This is a {NRSER::NicerError}.
+# 
+class NRSER::Types::FromStringError < ::ArgumentError
+  
+  # Mixins
+  # ==========================================================================
+  
+  # Make life better.
+  include NRSER::NicerError
+  
+  
+  # Attributes
+  # ========================================================================
+  
+  # The type that was checked against.
+  # 
+  # @return [NRSER::Types::Type]
+  #     
+  attr_reader :type
+  
+  
+  # The string we were trying to load from.
+  # 
+  # @return [String]
+  #     
+  attr_reader :string
+  
+  
+  # Constructor
+  # ========================================================================
+  
+  # Construct a `FromStringError`.
+  # 
+  # @param *message (see NRSER::NicerError#initialize)
+  # 
+  # @param [String] string:
+  #   The string the type was trying to load a value from.
+  # 
+  # @param [NRSER::Types::Type] type:
+  #   The type that was trying to load.
+  # 
+  # @param **kwds
+  #   See {NRSER::NicerError#initialize}
+  # 
+  def initialize *message, string:, type:, **kwds
+    @string = string
+    @type = type
+    
+    super \
+      *message,
+      type: type,
+      string: string,
+      **kwds
+  end
+  
+  
+  # Main message to use when none provided to {#initialize}.
+  # 
+  # @return [String]
+  # 
+  def default_message
+    ["Failed to load type", type.name, "from string", string.inspect]
+  end
+  
+end # class NRSER::Types::TypeError

data/lib/nrser/types/factory.rb

@@ -0,0 +1,91 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+
+# Refinements
+# =======================================================================
+
+
+# Declarations
+# =======================================================================
+
+
+# Definitions
+# =======================================================================
+
+
+# @todo document NRSER::Types::Factory module.
+module NRSER::Types::Factory
+  
+  # Define a type factory.
+  # 
+  # @!macro [attach] factory
+  #   @param [Hash] **options
+  #     Common type construction options, see {Type#initialize}.
+  #   
+  #   @return [NRSER::Types::Type]
+  #     The type.
+  # 
+  def def_factory name, maybe: true, aliases: [], &body
+    define_singleton_method name, &body
+    
+    aliases.each do |alias_name|
+      if self.respond_to? alias_name
+        alias_name = alias_name + '_'
+      end
+      
+      singleton_class.send :alias_method, alias_name, name
+    end
+    
+    if maybe && !name.to_s.end_with?( '?' )
+      maybe_name = "#{ name }?".to_sym
+      
+      if self.respond_to? maybe_name
+        maybe_name = "#{ name }_?".to_sym
+      end
+      
+      # HACK  Ugh maybe I wrote this quick to fix it, not sure if it's a decent
+      #       idea.. basically, need to figure out what `options` keys go
+      #       to {.maybe} and which ones go to the regular factory... matters
+      #       for shit like {.attrs} and {.hash_type} 'cause they use option
+      #       keys (whether they *should* is something I've debated... sigh,
+      #       it is what it is for now).
+      #       
+      #       So they options that go to {.maybe} just go strait through to
+      #       {Type#initialize}, so just grab that method, see what keys it
+      #       takes, and then can slice and dice off that...
+      # 
+      maybe_option_keys = Set.new \
+        NRSER::Types::Type.
+          instance_method( :initialize ).
+          parameters.
+          select { |param_type, name| param_type == :key }.
+          map { |param_type, name| name }
+      
+      define_singleton_method maybe_name do |*args, **options|
+        maybe_options = options.slice *maybe_option_keys
+        factory_options = options.except *maybe_option_keys
+        
+        maybe public_send( name, *args, **factory_options ), **maybe_options
+      end
+      
+      aliases.each do |alias_name|
+        singleton_class.send :alias_method, "#{ alias_name }?", maybe_name
+      end
+      
+    end
+  end
+  
+end # module NRSER::Types::Factory

data/lib/nrser/types/hashes.rb

@@ -1,41 +1,185 @@
-require 'nrser/refinements'
-require 'nrser/types/type'
-
-using NRSER
+require_relative './type'
   
 module NRSER::Types
-
+  
+  # A type who's members simply are {Hash} instances.
+  # 
+  # Implements {#from_s} to provide JSON/YAML detection, as well as "simple"
+  # loading aimed at CLI option values.
+  # 
   class HashType < IsA
-    attr_reader :keys, :values #, :including, :exactly, :min, :max
+  
+    # Constructor
+    # ========================================================================
     
-    def initialize  keys: NRSER::Types::ANY,
-                    values: NRSER::Types::ANY,
-                    **options
+    # Instantiate a new `HashType`.
+    def initialize **options
       super ::Hash, **options
+    end # #initialize
+    
+    
+    # Instance Methods
+    # ========================================================================
+    
+    # In order to provide the same interface as {HashOfType}, this method
+    # always returns {NRSER::Types.any}.
+    # 
+    # @return [NRSER::Types::Type]
+    # 
+    def keys; NRSER::Types.any; end
+    
+    
+    # In order to provide the same interface as {HashOfType}, this method
+    # always returns {NRSER::Types.any}.
+    # 
+    # @return [NRSER::Types::Type]
+    # 
+    def values; NRSER::Types.any; end
+    
+    
+    protected
+    # ========================================================================
+
+      # Hook to provide custom loading from strings, which will be called by
+      # {NRSER::Types::Type#from_s}, unless a `@from_s`
+      # 
+      def custom_from_s string
+        # Does it looks like a JSON / inline-YAML object?
+        if NRSER.looks_like_json_object? string
+          # It does! Load it
+          begin
+            return YAML.load string
+          rescue
+            # pass - if we failed to load as JSON, it may just not be JSON, and
+            # we can try the split approach below.
+          end
+        end
+        
+        # Try parsing as a "simple string", aimed at CLI option values.
+        from_simple_s string
+      end
+      
+      
+      def from_simple_s string
+        hash = {}
+        
+        pair_strs = string.split NRSER::Types::ArrayType::DEFAULT_SPLIT_WITH
+        
+        pair_strs.each do |pair_str|
+          key_str, match, value_str = pair_str.rpartition /\:\s*/m
+          
+          if match.empty?
+            raise NRSER::Types::FromStringError.new(
+              "Could not split pair string", pair_str,
+              type: self,
+              string: string,
+              pair_str: pair_str,
+            ) do
+              <<~END
+                Trying to parse a {Hash} out of a string using the "simple"
+                approach, which splits
+                
+                1.  First by `,` (followed by any amount of whitespace)
+                2.  Then by the last `:` in each of those splits (also followed)
+                    by any amount of whitespace)
+              END
+            end
+          end
+          
+          key = if keys == NRSER::Types.any
+            key_str
+          else
+            keys.from_s key_str
+          end
+          
+          value = if values == NRSER::Types.any
+            value_str
+          else
+            values.from_s value_str
+          end
+          
+          hash[key] = value
+        end
+        
+        hash
+      end # #from_simple_s
+      
+    public # end protected *****************************************************
+    
+  end # class HashType
+  
+  
+  # A {Hash} type with typed keys and/or values.
+  # 
+  class HashOfType < HashType
+    
+    # Attributes
+    # ========================================================================
+    
+    # The type of the hash keys.
+    # 
+    # @return [NRSER::Types::Type]
+    #     
+    attr_reader :keys
+    
+    
+    # The type of the hash values.
+    # 
+    # @return [NRSER::Types::Type]
+    # 
+    attr_reader :values
+    
+    
+    # Constructor
+    # ========================================================================
+    
+    def initialize  keys: NRSER::Types.any,
+                    values: NRSER::Types.any,
+                    **options
+      super **options
       
       @keys = NRSER::Types.make keys
       @values = NRSER::Types.make values
     end
     
-    def test value
-      return false unless super(value)
-      
-      if keys == NRSER::Types::ANY && values == NRSER::Types::ANY
-        return true
-      end
+    
+    # Instance Methods
+    # ========================================================================
+    
+    # Overridden to check that both the {#keys} and {#values} types can
+    # load from a string.
+    # 
+    # @see NRSER::Types::Type#has_from_s?
+    # 
+    def has_from_s?
+      !@from_s.nil? || [keys, values].all?( &:has_from_s )
+    end
+    
+    
+    # @see NRSER::Types::Type#test
+    # 
+    # @return [Boolean]
+    # 
+    def test? value
+      return false unless super( value )
       
       value.all? { |k, v|
-        keys.test(k) && values.test(v)
+        keys.test( k ) && values.test( v )
       }
     end
     
-    def default_name
-      "Hash{#{ @keys.name }=>#{ @values.name }}"
+    
+    # @see NRSER::Types::Type#explain
+    # 
+    # @return [String]
+    # 
+    def explain
+      "Hash<#{ keys.explain }, #{ values.explain }>"
     end
+    
   end # HashType
+    
   
-  
-
   # Type satisfied by {Hash} instances.
   # 
   # @param [Array] *args
@@ -47,14 +191,15 @@ module NRSER::Types
   # @return [NRSER::Types::Type]
   #   Newly constructed hash type from `args`.
   # 
-  def_factory :hash_type, aliases: [:dict, :hash_] do |*args|
-    if args.empty?
-      HASH
+  def_factory(
+    :hash_type,
+    aliases: [ :dict, :hash_ ]
+  ) do |**kwds|
+    if kwds.key?( :keys ) || kwds.key?( :values )
+      HashOfType.new **kwds
     else
-      HashType.new *args
+      HashType.new **kwds
     end
   end
   
-  HASH = HashType.new.freeze
-  
 end

data/lib/nrser/types/in.rb

@@ -1,26 +1,39 @@
-# Refinements
-# =======================================================================
-
-using NRSER
-
-
-# Definitions
-# =======================================================================
+# encoding: UTF-8
+# frozen_string_literal: true
 
 module NRSER::Types
   
   # Type that tests value for membership in a group object via that object's
   # `#include?` method.
   # 
+  # @todo
+  #   I think I want to get rid of {.where}... which would elevate this to
+  #   it's own class as a "fundamental" concept (I guess)... not so sure,
+  #   really. The idea of membership is pretty wide-spread and important,
+  #   but it's a bit a vague and inconsistently implemented things.
+  # 
   # @param [#include?] group
   #   `#include?` will be called on this value to determine type membership.
   # 
   # @return [NRSER::Types::Type]
   # 
-  def self.in group, **options
-    where( name: "In(#{ group })", **options ) { |value|
-      group.include? value
-    }
+  def_factory(
+    :in,
+    aliases: [ :member_of ],
+  ) do |group, **options|
+    unless group.respond_to? :include?
+      raise NRSER::ArgumentError,
+        "In `group` must respond to `:include?`",
+        group: group
+    end
+    
+    # Provide a some-what useful default name
+    options[:name] ||= "In<#{ NRSER.smart_ellipsis group.inspect, 64 }>"
+    
+    # Unless a `from_s` is provided, just use the identity
+    options[:from_s] ||= ->( s ) { s }
+    
+    where( **options ) { |value| group.include? value }
   end # .in
   
 end # module NRSER::Types

data/lib/nrser/types/is.rb

@@ -1,22 +1,58 @@
-require 'nrser/refinements'
-require 'nrser/types/type'
-using NRSER
+
+# Requirements
+# ========================================================================
+
+# Stdlib
+# ------------------------------------------------------------------------
+
+# Deps
+# ------------------------------------------------------------------------
+
+# Need {Module#anonymous?}
+require 'active_support/core_ext/module/anonymous'
+
+
+# Project / Package
+# ------------------------------------------------------------------------
+
+require_relative './type'
+
 
 module NRSER::Types
+  
+  # Type satisfied only by it's exact {#value} object (identity comparison
+  # via `#equal?`).
+  # 
   class Is < NRSER::Types::Type
+    
+    # Attributes
+    # ========================================================================
+    
     attr_reader :value
     
     def initialize value, **options
       super **options
-      
       @value = value
     end
     
-    def default_name
-      "Is(#{ @value.inspect })"
+    def explain
+      case value
+      when Module
+        module_type = if value.is_a?( Class ) then 'Class' else 'Module' end
+        
+        name = if value.anonymous?
+          value.to_s.split( ':' ).last[0...-1]
+        else
+          value.name
+        end
+        
+        "#{ module_type }<#{ name }>"
+      else
+        value.inspect
+      end
     end
     
-    def test value
+    def test? value
       @value.equal? value
     end
     
@@ -26,19 +62,15 @@ module NRSER::Types
         @value == other.value )
     end
     
-    # @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 ≡ #{ @value.inspect } }"
-    end
-    
-    alias_method :inspect, :to_s
   end # Is
   
-  # an exact value (using ===)
-  def self.is value, **options
+  
+  # Satisfied by the exact value only (identity comparison via
+  # `#equal?`).
+  # 
+  # Useful for things like {Module}, {Class}, {Fixnum}, {Symbol}, `true`, etc.
+  # 
+  def_factory :is do |value, **options|
     Is.new value, **options
   end