nrser 0.0.26 → 0.0.27

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5695621d94d38882e9dcce612c022ac723febf5e
-  data.tar.gz: 825fe26548e53f4f8a72138fabb9554832392c8a
+  metadata.gz: 9a096ba06bf0367538de51b0411db1b77e2bcd8e
+  data.tar.gz: fc229e219af929a41b380c820e3fb797bc3f823f
 SHA512:
-  metadata.gz: 35da0260954c54d63cb02aadd26d110810bdcf776bfc9e7dfe5966512411d9b42b6a2d49474e4db3025891b976b9d8c72f140c440f96a402931b5141811b2fd6
-  data.tar.gz: 17a5658d7d56c4a93a8f1eda5fa8782f41452fbc64a4fb195daeca9e1b22fe5e34f6329b595db6e73a23651e61f2b3ab47cec66e74e90a20a2d3d37819ada1b5
+  metadata.gz: 02e902e272bf5ab0b42d74d903fdb4179fd82f3476a25a92bba11d5c6ea7a8812b4e08652355be0179eb7873f0ae344296fa93b4639cb79020f32e61b7cf143a
+  data.tar.gz: 343deeec75ba3b162c8fea5aa26a342cf20c3e66df228250dfae60e2a1214962b475d6322a710b15d797ea99b4d7d4b4efb7c18513b907ed0484ce07886dc8fc

data/lib/nrser.rb

@@ -11,6 +11,7 @@ require_relative './nrser/proc'
 require_relative './nrser/collection'
 require_relative './nrser/object'
 require_relative './nrser/string'
+require_relative './nrser/text'
 require_relative './nrser/binding'
 require_relative './nrser/exception'
 require_relative './nrser/enumerable'

data/lib/nrser/array.rb

@@ -12,4 +12,19 @@ module NRSER
     array[1..-1]
   end # .rest
   
+  
+  # A destructive partition.
+  def self.extract_from_array! array, &block
+    extracted = []
+    array.reject! { |entry|
+      test = block.call entry
+      if test
+        extracted << entry
+      end
+      test
+    }
+    extracted
+  end
+  
+  
 end # module NRSER

data/lib/nrser/binding.rb

@@ -5,7 +5,13 @@ module NRSER
 
     def erb bnd, str
       require 'erb'
-      filter_repeated_blank_lines ERB.new(dedent(str)).result(bnd)
+      
+      filter_repeated_blank_lines(
+        with_indent_tagged( dedent( str ) ) { |tagged_str|
+          ERB.new( tagged_str ).result( bnd )
+        },
+        remove_leading: true
+      )
     end # erb
 
     alias_method :template, :erb

data/lib/nrser/enumerable.rb

@@ -107,6 +107,26 @@ module NRSER
     end # #find_only
     
     
+    # Return the only entry if the enumerable has `#count` one. Otherwise,
+    # return `default` (which defaults to `nil`).
+    # 
+    # @param [Enumerable] enum
+    #   Enumerable in question.
+    # 
+    # @param [Object] default:
+    #   Value to return if `enum` does not have only one entry.
+    # 
+    # @return [Object]
+    #   The only entry in `enum` if it has only one, else `default`.
+    # 
+    def only enum, default: nil
+      if enum.count == 1
+        enum.first
+      else
+        default
+      end
+    end
+    
     
     # @todo Document only method.
     # 
@@ -117,7 +137,7 @@ module NRSER
     #   @todo Document return value.
     # 
     def only! enum
-      unless enum.length == 1
+      unless enum.count == 1
         raise TypeError.new squish <<-END
           Expected enumerable #{ enum.inspect } to have exactly one entry.
         END

data/lib/nrser/errors.rb

@@ -1,9 +1,59 @@
-
 module NRSER
-
-  class Error < StandardError; end
   
-  class ConflictError < Error; end
-
-end
+  # Indicates some piece of application state is in conflict with the attempted
+  # operation.
+  class ConflictError < StandardError; end
+  
+  
+  # Extension of Ruby's {NotImplementedError} to provide a useful message 
+  # and convenient constructor for abstract methods.
+  # 
+  # @example
+  #   
+  #   def f
+  #     raise NRSER::AbstractMethodError.new( self, __method__ )
+  # 
+  # 
+  class AbstractMethodError < NotImplementedError
+    
+    # Construct a new `AbstractMethodError`.
+    # 
+    # @param [Object] instance
+    #   Instance that invoked the abstract method.
+    # 
+    # @param [Symbol | String] method_name
+    #   Name of abstract method.
+    # 
+    def initialize instance, method_name
+      @instance = instance
+      @method_name = method_name
+      @method = instance.method @method_name
+      
+      message = if @method.owner == instance.class
+        NRSER.dedent <<-END
+          Method #{ @method.owner.name }##{ @method_name } is abstract, meaning 
+          #{ @method.owner.name } is an abstract class and the invoking 
+          instance #{ @instance } should NOT have been constructed.
+        END
+      else
+        NRSER.squish <<-END
+          Method #{ @method.owner.name }##{ @method_name } is abstract and 
+          has not been implemented in invoking class #{ @instance.class }.
+          
+          If you *are* developing the invoking class #{ @instance.class } it
+          (or a parent class between it and #{ @method.owner.name }) must 
+          implement ##{ @method_name }.
+          
+          If you *are not* developing #{ @instance.class } it should be treated
+          as an abstract base class and should NOT be constructed. You need to
+          find a subclass of #{ @instance.class } to instantiate or write 
+          your own.
+        END
+      end
+      
+      super message
+    end # #initialize
+    
+  end # class AbstractMethodError
 
+end # module NRSER

data/lib/nrser/hash/deep_merge.rb

@@ -42,7 +42,7 @@ module NRSER
                                   other_value.is_a?(Hash)
         deep_merge this_value, other_value, &block
       else
-        if block_given? && key?(current_key)
+        if block_given? && base_hash.key?( current_key )
           block.call(current_key, this_value, other_value)
         else
           other_value

data/lib/nrser/message.rb

@@ -20,6 +20,39 @@ module NRSER
   # sent to an object as a method call, especially in testing.
   # 
   class Message
+    # Class Methods
+    # =====================================================================
+    
+    # Instantiate a message from the arguments, unless they already are one.
+    # 
+    # @overload from symbol, *args, &block
+    #   Create a new instance from the arguments by passing them to 
+    #   {NRSER::Message.new}.
+    # 
+    #   @param [NRSER::Message] message
+    #     An already instantiated message, which is simple returned.
+    #   
+    #   @return [NRSER::Message]
+    #     Message created from the arguments.
+    # 
+    # @overload from message
+    #   Convenience method to return the message if it's the only argument.
+    #   
+    #   @param [NRSER::Message] message
+    #     An already instantiated message, which is simple returned.
+    #   
+    #   @return [NRSER::Message]
+    #     The `message` argument.
+    # 
+    def self.from *args, &block
+      if args.length == 1 && args[0].is_a?( Message )
+        args[0]
+      else
+        new *args, &block
+      end
+    end # .from
+    
+    
     # Name of method the message is for.
     # 
     # @return [Symbol | String]

data/lib/nrser/meta/props.rb

@@ -10,7 +10,8 @@ module NRSER
 module Meta
 
 module Props
-  CLASS_KEY = '__class__';
+  DEFAULT_CLASS_KEY = '__class__';
+  
   PROPS_VARIABLE_NAME = :@__NRSER_props
   PROP_VALUES_VARIABLE_NAME = :@__NRSER_prop_values
   
@@ -51,27 +52,67 @@ module Props
   # reasonable to use on untrusted data.
   # 
   # @param [Hash<String, Object>] data
+  #   Data hash to load from.
   # 
-  # @return [Object]
-  #   @todo Document return value.
-  # 
+  # @param 
   # 
+  # @return [NRSER::Meta::Props]
+  #   Instance of a propertied class.
   # 
-  def self.from_data data
+  def self.UNSAFE_load_instance_from_data data, class_key: DEFAULT_CLASS_KEY
     t.hash_.check data
     
-    unless data.key?(CLASS_KEY)
-      raise ArgumentError.new <<-END.dedent
-        Data is missing #{ CLASS_KEY } key - no idea what class to instantiate.
+    unless data.key?( class_key )
+      raise ArgumentError.new binding.erb <<-ERB
+        Data is missing <%= class_key %> key - no idea what class to 
+        instantiate.
+        
+        Data:
         
-        #{ data.pretty_inspect }
-      END
+            <%= data.pretty_inspect %>
+        
+      ERB
     end
     
-    class_name = t.str.check data[CLASS_KEY]
+    # Get the class name from the data hash using the key, checking that it's
+    # a non-empty string.
+    class_name = t.non_empty_str.check data[class_key]
+    
+    # Resolve the constant at that name.
     klass = class_name.to_const
+    
+    # Make sure it's one of ours
+    unless klass.included_modules.include?( NRSER::Meta::Props )
+      raise ArgumentError.new binding.erb <<-ERB
+        Can not load instance from data - bad class name.
+        
+        Extracted class name
+        
+            <%= class_name.inspect %>
+        
+        from class key
+        
+            <%= class_key.inspect %>
+        
+        which resolved to constant
+        
+            <%= klass.inspect %>
+        
+        but that class does not include the NRSER::Meta::Props mixin, which we
+        check for to help protect against executing an unrelated `.from_data`
+        class method when attempting to load.
+        
+        Data:
+        
+            <%= data.pretty_inspect %>
+        
+      ERB
+    end
+    
+    # Kick off the restore and return the result
     klass.from_data data
-  end # .from_data
+    
+  end # .UNSAFE_load_instance_from_data
   
   
   # Hook to extend the including class with {NRSER::Meta::Props:ClassMethods}
@@ -176,7 +217,24 @@ module Props
     # @return [self]
     # 
     def from_data data
-      self.new data.symbolize_keys
+      values = {}
+      props = self.props
+      
+      data.each { |data_key, data_value|
+        prop_key = case data_key
+        when Symbol
+          data_key
+        when String
+          data_key.to_sym
+        end
+        
+        if  prop_key &&
+            prop = props[prop_key]
+          values[prop_key] = prop.value_from_data data_value
+        end
+      }
+      
+      self.new values
     end # #from_data
     
     
@@ -240,14 +298,18 @@ module Props
   # @return [Hash<String, Object>]
   #   @todo Document return value.
   # 
-  def to_data only_own: false, only_primary: false, add_class: true
+  def to_data only_own: false,
+              only_primary: false,
+              add_class: true,
+              class_key: NRSER::Meta::Props::DEFAULT_CLASS_KEY
+              
     self.class.props(only_own: false, only_primary: false).
       map { |name, prop|
         [name.to_s, prop.to_data(self)]
       }.
       to_h.
       tap { |hash|
-        hash[CLASS_KEY] = self.class.name if add_class
+        hash[class_key] = self.class.name if add_class
       }
   end # #to_data
   

data/lib/nrser/meta/props/prop.rb

@@ -1,4 +1,18 @@
-require 'nrser/no_arg'
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+
+# Refinements
+# =======================================================================
 
 require 'nrser/refinements'
 using NRSER
@@ -6,41 +20,188 @@ using NRSER
 require 'nrser/refinements/types'
 using NRSER::Types
 
-module NRSER 
-module Meta
-module Props
+
+# Declarations
+# =======================================================================
+
+module NRSER; end
+module NRSER::Meta; end
+module NRSER::Meta::Props; end
+
+
+# Definitions
+# =======================================================================
+
+# `Prop` instances hold the configuration for a property defined on propertied
+# classes.
+# 
+# Props are immutable by design.
+# 
+class NRSER::Meta::Props::Prop
+  
+  # The class the prop was defined in.
+  # 
+  # @return [Class]
+  #     
+  attr_reader :defined_in
   
-class Prop
-  attr_accessor :defined_in,
-                :name,
-                :type,
-                :source
   
+  # The name of the prop, which is used as it's method name and key where
+  # applicable.
+  # 
+  # @return [Symbol]
+  #     
+  attr_reader :name
   
+  
+  # The type of the valid values for the property.
+  # 
+  # @return [NRSER::Types::Type]
+  #     
+  attr_reader :type
+  
+    
+  # Optional name of instance variable (including the `@` prefix) or getter
+  # method (method that takes no arguments) that provides the property's
+  # value.
+  # 
+  # Props that have a source are considered *derived*, those that don't are 
+  # called *primary*.
+  # 
+  # @return [Symbol | String]
+  #     
+  attr_reader :source
+  
+  
+  # Constructor
+  # =====================================================================
+  
+  # Instantiate a new `Prop` instance.
+  # 
+  # You should not need to construct a `Prop` directly unless you are doing
+  # custom meta-programming - they should be constructed for you via the
+  # `.prop` "macro" defined at {NRSER::Meta::Props::ClassMethods#prop}
+  # that is extended in to classes including {NRSER::Meta::Props}.
+  # 
   def initialize  defined_in,
                   name,
                   type: t.any,
-                  default: NRSER::NO_ARG,
+                  default: nil,
+                  default_from: nil,
                   source: nil,
-                  to_data: nil
+                  to_data: nil,
+                  from_data: nil
     
+    # Set these up first so {#to_s} works in case we need to raise errors.
     @defined_in = defined_in
     @name = name
     @type = t.make type
-    @source = source
-    @default = default
+    
     @to_data = to_data
+    @from_data = from_data
+    
+    # Source
     
-    if @source.nil?
+    @source = source # TODO fix this: t.maybe( t.label ).check source
+    
+    # Detect if the source 
+    if source.nil?
       @instance_variable_source = false
     else
+      # TODO Check that default and default_from are `nil`, make no sense here
+      
       source_str = source.to_s
       @instance_variable_source = source_str[0] == '@'
     end
-  end
+    
+    # Defaults
+    
+    # Can't provide both default and default_from
+    unless default.nil? || default_from.nil?
+      raise NRSER::ConflictError.new binding.erb <<-ERB
+        Both `default:` and `default_from:` keyword args provided when 
+        constructing <%= self %>. At least one must be `nil`.
+        
+        default:
+            <%= default.pretty_inspect %>
+        
+        default_from:
+            <%= default_from.pretty_inspect %>
+        
+      ERB
+    end
+    
+    if default_from.nil?
+      # We are going to use `default`
+          
+      # Validate `default` value
+      if default.nil?
+        # If it's `nil` we still want to see if it's a valid value for the type
+        # so we can report if this prop has a default value or not.
+        # 
+        # However, we only need to do that if there is no `source`
+        # 
+        @has_default = if source.nil?
+          @type.test default
+        else
+          # NOTE  This is up for debate... does a derived property have a 
+          #       default? What does that even mean?
+          true # false ?
+        end
+        
+      else
+        # Check that the default value is valid for the type, raising TypeError
+        # if it isn't.
+        @type.check( default ) { |type:, value:|
+          binding.erb <<-ERB
+            Default value is not valid for <%= self %>:
+            
+                <%= value.pretty_inspect %>
+            
+          ERB
+        }
+        
+        # If we passed the check we know the value is valid
+        @has_default = true
+        
+        # Set the default value to `default`, freezing it since it will be 
+        # set on instances without any attempt at duplication, which seems like
+        # it *might be ok* since a lot of prop'd classes are being used
+        # immutably.
+        @default_value = default.freeze
+      end
+      
+    else
+      # `default_from` is not `nil`, so we're going to use that.
+      
+      # This means we "have" a default since we believe we can use it to make
+      # one - the actual values will have to be validates at that point.
+      @has_default = true
+      
+      # And set it.
+      # 
+      # TODO validate it's something reasonable here?
+      # 
+      @default_from = default_from
+    end
+    
+  end # #initialize
+  
+  
+  # Full name with class prop was defined in.
+  # 
+  # @example
+  #   MyMod::SomeClass.props[:that_prop].full_name
+  #   # => 'MyMod::SomeClass#full_name'
+  # 
+  # @return [String]
+  # 
+  def full_name
+    "#{ defined_in.name }##{ name }"
+  end # #full_name
   
   
-  # @todo Document default? method.
+  # Test if this prop is configured to provide default values - 
   # 
   # @param [type] arg_name
   #   @todo Add name param description.
@@ -48,9 +209,12 @@ class Prop
   # @return [return_type]
   #   @todo Document return value.
   # 
-  def default?
-    @default != NRSER::NO_ARG
-  end # #default?
+  def has_default?
+    @has_default
+  end # #has_default?
+  
+  # Old name
+  alias_method :default?, :has_default?
   
   
   def default
@@ -143,10 +307,19 @@ class Prop
   #   @todo Document return value.
   # 
   def set instance, value
-    unless type.test value
-      raise TypeError.new NRSER.squish <<-END
-        #{ defined_in }##{ name } must be of type #{ type };
-        found #{ value.inspect }
+    type.check( value ) do
+      binding.erb <<-END
+        Value of type <%= value.class.name %> for prop <%= self.full_name %> 
+        failed type check.
+        
+        Must satisfy type:
+        
+            <%= type %>
+        
+        Given value:
+        
+            <%= value.pretty_inspect %>
+        
       END
     end
     
@@ -167,16 +340,20 @@ class Prop
       set instance, values[name]
     else
       if default?
-        set instance, if !default.nil? && default.respond_to?( :dup )
-          default.dup
-        else
-          default
-        end
+        # set instance, if !default.nil? && default.respond_to?( :dup )
+        #   default.dup
+        # else
+        #   default
+        # end
+        set instance, default
       else
-        raise TypeError.new NRSER.squish <<-END
-          Prop #{ name } has no default value and no value was provided in
-          values #{ values.inspect }.
-        END
+        raise TypeError.new binding.erb <<-ERB
+          Prop <#= full_name %> has no default value and no value was provided 
+          in values:
+          
+              <%= values.pretty_inspect %>
+          
+        ERB
       end
     end
   end # #set_from_hash
@@ -251,14 +428,69 @@ class Prop
   end # #to_data
   
   
+  # @todo Document value_from_data method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def value_from_data data
+    value = case @from_data
+    when nil
+      # This {Prop} does not have any custom `from_data` instructions, which
+      # means we must rely on the {#type} to covert *data* to a *value*.
+      # 
+      if type.has_from_data?
+        type.from_data data
+      else
+        data
+      end
+      
+    when Symbol, String
+      # The custom `from_data` configuration specifies a string or symbol name,
+      # which we interpret as a class method on the defining class and call
+      # with the data to produce a value.
+      @defined_in.send @to_data, data
+    
+    when Proc
+      # The custom `from_data` configuration provides a procedure, which we
+      # call with the data to produce the value.
+      @from_data.call data
+      
+    else
+      raise TypeError.new binding.erb <<-ERB
+        Expected `@from_data` to be Symbol, String or Proc;
+        found <%= @from_data.class %>.
+        
+        Acceptable types:
+        
+        -   Symbol or String
+            -   Name of class method on the class this property is defined in
+                (<%= @defined_in %>) to call with data to convert it to a
+                property value.
+                
+        -   Proc
+            -   Procedure to call with data to convert it to a property value.
+        
+        Found `@from_data`:
+        
+            <%= @from_data.pretty_inspect %>
+        
+        (type <%= @from_data.class %>)
+        
+      ERB
+    end
+      
+  end # #value_from_data
+  
+  
   # @return [String]
   #   a short string describing the instance.
   # 
   def to_s
-    <<-END.squish
-      #<#{ self.class.name }
-        #{ @defined_in.name }##{ @name }:#{ @type }>
-    END
+    "#<#{ self.class.name } #{ full_name }:#{ type }>"
   end # #to_s  
   
   
@@ -273,15 +505,15 @@ class Prop
     #   @todo Document return value.
     # 
     def values instance
-      unless instance.instance_variable_defined? PROP_VALUES_VARIABLE_NAME
-        instance.instance_variable_set PROP_VALUES_VARIABLE_NAME, {}
+      unless instance.instance_variable_defined?(
+        NRSER::Meta::Props::PROP_VALUES_VARIABLE_NAME
+      )
+        instance.instance_variable_set \
+          NRSER::Meta::Props::PROP_VALUES_VARIABLE_NAME, {}
       end
       
-      instance.instance_variable_get PROP_VALUES_VARIABLE_NAME
+      instance.instance_variable_get \
+        NRSER::Meta::Props::PROP_VALUES_VARIABLE_NAME
     end # #value
   
-end # class Prop
-  
-end # module Props
-end # module Meta
-end # module NRSER
+end # class NRSER::Meta::Props::Prop