nrser 0.2.2 → 0.3.0

data/lib/nrser/props/mutable/stash.rb

@@ -0,0 +1,199 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+# Need {NRSER::Props} to include
+require_relative '../../props'
+
+# Need {NRSER::Stash} itself
+require 'nrser/labs/stash'
+
+# Gonna use {NRSER::Props::Storage::Key} for storage
+require_relative '../storage/key'
+
+
+# Declarations
+# =======================================================================
+
+module NRSER::Props::Mutable; end
+
+
+# Definitions
+# =======================================================================
+
+module NRSER::Props::Mutable::Stash
+  
+  # Constants
+  # ==========================================================================
+  
+  STORAGE = NRSER::Props::Storage::Key.new \
+              immutable: false,
+              key_type: :name,
+              get: :_raw_get,
+              put: :_raw_put
+  
+  
+  # Module Methods
+  # ======================================================================
+  
+  def self.included base
+    unless base < NRSER::Stash
+      raise binding.erb <<~END
+        This class is only for including in {Hash} subclasses!
+      END
+    end
+    
+    base.include NRSER::Props
+    base.include InstanceMethods
+    base.metadata.storage STORAGE
+    base.metadata.freeze
+  end
+  
+  # Methods to be mixed in at the class-level with
+  # {NRSER::Props::Mutable::Hash}.
+  module ClassMethods
+    
+    def [] *args
+      new ::Hash[*args]
+    end
+    
+  end # module ClassMethods
+  
+  
+  # Instance methods to mix in with {NRSER::Props::Mutable::Hash}.
+  # 
+  # We want these to *override* {NRSER::Props::InstanceMethods}, so they
+  # need to be separate so we can include them after {NRSER::Props} in
+  # {NRSER::Props::Mutable::Hash.included}.
+  # 
+  module InstanceMethods
+
+    def initialize_props values = {}
+      # Handles things like `[[:x, 1], [:y, 2]]`, since we know that's what is
+      # meant in that case
+      values = values.to_h unless values.respond_to?( :each_pair )
+      
+      self.class.metadata.
+        each_primary_prop_value_from( values ) { |prop, value|
+          _raw_put prop.name, value
+        }
+      
+      # Check additional type invariants
+      self.class.invariants.each do |type|
+        type.check self
+      end
+      
+      # Load in additional non-prop values, if any
+      # 
+      # TODO  Optimize
+      # 
+      
+      prop_names = self.class.metadata.prop_names
+      
+      values.each do |key, value|
+        unless prop_names.include? convert_key( key )
+          self[key] = value
+        end
+      end
+    end # #initialize_props
+    
+    
+    # Override {NRSER::Props::InstanceMethods#to_data} to handle non-prop
+    # values in the {NRSER::Stash}.
+    # 
+    # @param [Boolean] only_props:
+    #   When `true` only prop values will be added to the data hash.
+    #   
+    #   Otherwise, any non-prop keys and vales will be added as well
+    #   (default behavior).
+    # 
+    # @param **kwds
+    #   See {NRSER::Props::InstanceMethods#to_data}.
+    # 
+    # @return (see NRSER::Props::InstanceMethods#to_data)
+    # 
+    def to_data only_props: false, **kwds
+      hash = super **kwds
+      
+      unless only_props
+        each do |key, value|
+          # Data uses **string** keys
+          key = key.to_s
+          
+          # See if the key is missing
+          unless hash.key?( key.to_s )
+            # It is, so let's fill it in
+            
+            # If value knows how to be data, do that
+            value = value.to_data if value.respond_to?( :to_data )
+            
+            # Set the key/value pair
+            hash[key] = value
+          end
+        end
+      end
+      
+      hash
+    end # #to_data
+    
+    
+    def convert_key key
+      case key
+      when Symbol
+        key
+      when String
+        sym = key.to_sym
+        if self.metadata[ sym ]
+          sym
+        else
+          key
+        end
+      else
+        key
+      end
+    end
+    
+    
+    # Store a value at a key. If the key is a prop name, store it through the
+    # prop, which will check it's type.
+    # 
+    # @param [Symbol | String] key
+    # @param [VALUE] value
+    # 
+    # @return [VALUE]
+    #   The stored value.
+    # 
+    def put key, value
+      key = convert_key key
+      
+      if (prop = self.class.metadata[ key ])
+        prop.set self, value
+      else
+        # We know {#convert_value} is a no-op so can skip it
+        _raw_put key, value
+      end
+    end # #put
+    
+    
+    def dup
+      self.class.new( self ).tap do |new_stash|
+        set_defaults new_stash
+      end
+    end
+    
+    
+    # Need to patch `#merge` since {NRSER::Props::InstanceMethods} defines
+    # it, which overrides {NRSER::Stash#merge}, so we just put it back.
+    # 
+    def merge other_hash = {}, &block
+      dup.update other_hash, &block
+    end
+    
+  end # module InstanceMethods
+  
+end # module NRSER::Props::Mutable::Stash

data/lib/nrser/{meta/props → props}/prop.rb

@@ -1,7 +1,20 @@
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+require 'nrser/refinements/types'
+
+
 # Refinements
 # =======================================================================
 
-using NRSER
 using NRSER::Types
 
 
@@ -9,8 +22,7 @@ using NRSER::Types
 # =======================================================================
 
 module NRSER; end
-module NRSER::Meta; end
-module NRSER::Meta::Props; end
+module NRSER::Props; end
 
 
 # Definitions
@@ -21,7 +33,9 @@ module NRSER::Meta::Props; end
 # 
 # Props are immutable by design.
 # 
-class NRSER::Meta::Props::Prop
+class NRSER::Props::Prop
+  
+  include NRSER::Log::Mixin
   
   # The class the prop was defined in.
   # 
@@ -38,13 +52,27 @@ class NRSER::Meta::Props::Prop
   attr_reader :name
   
   
+  # The key under which the value will be stored in the storage.
+  # 
+  # @return [nil | Integer]
+  #     
+  attr_reader :index
+  
+  
   # The type of the valid values for the property.
   # 
   # @return [NRSER::Types::Type]
   #     
   attr_reader :type
   
-    
+  
+  # Names of any props this one depends on (to create a default).
+  # 
+  # @return [Array<Symbol>]
+  #     
+  attr_reader :deps
+  
+  
   # Optional name of instance variable (including the `@` prefix) or getter
   # method (method that takes no arguments) that provides the property's
   # value.
@@ -68,6 +96,13 @@ class NRSER::Meta::Props::Prop
   attr_reader :source
   
   
+  # TODO document `aliases` attribute.
+  # 
+  # @return [Array<Symbol>]
+  #     
+  attr_reader :aliases
+  
+  
   # Constructor
   # =====================================================================
   
@@ -75,8 +110,8 @@ class NRSER::Meta::Props::Prop
   # 
   # 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}.
+  # `.prop` "macro" defined at {NRSER::Props::Props::ClassMethods#prop}
+  # that is extended in to classes including {NRSER::Props::Props}.
   # 
   # @param [nil | Proc | Object] default:
   #   A default value or a {Proc} used to get default values for *primary*
@@ -101,16 +136,29 @@ class NRSER::Meta::Props::Prop
                   default: nil,
                   source: nil,
                   to_data: nil,
-                  from_data: nil
+                  from_data: nil,
+                  index: nil,
+                  reader: nil,
+                  writer: nil,
+                  aliases: []
     
     # Set these up first so {#to_s} works in case we need to raise errors.
     @defined_in = defined_in
     @name = t.sym.check name
+    @index = t.non_neg_int?.check! index
     @type = t.make type
     
+    # Will be overridden in {#init_default!} if needed
+    @deps = []
+    
     @to_data = to_data
     @from_data = from_data
     
+    @reader = t.bool?.check! reader
+    @writer = t.bool?.check! writer
+    
+    @aliases = t.array( t.sym ).check! aliases
+    
     # Source
     
     # normalize source to {nil}, {Symbol} or {Proc}
@@ -147,7 +195,7 @@ class NRSER::Meta::Props::Prop
       # for sourced props
       if source?
         raise ArgumentError.new binding.erb <<-END
-          Can not construct {<%= self.class.name %>} with `default` and `source`
+          Can not construct {<%= self.class.safe_name %>} with `default` and `source`
           
           Props with {#source} always get their value from that source, so
           defaults don't make any sense.
@@ -166,8 +214,47 @@ class NRSER::Meta::Props::Prop
         END
       end
       
-      # It must be a {Proc} or be frozen
-      unless Proc === default || default.frozen?
+      if Proc === default
+        case default.arity
+        when 0
+          # pass, no deps
+        when 1
+          # Check that it's valid and set deps
+          @deps = default.parameters.map do |param|
+            unless  Array === param &&
+                    :keyreq == param[0]
+              raise ArgumentError.new binding.erb <<~END
+                Prop default Proc that take args must take only required
+                keywords (`:keyreq` type)
+                
+                This is because this is how the props system figures out
+                any dependency orders.
+                
+                Found:
+                
+                    <%= default.parameters %>
+                
+                For `default` for prop <%= full_name %>:
+                
+                    <%= self.pretty_inspect %>
+                
+              END
+            end
+            
+            # The keyword name
+            param[1]
+          end
+        else
+          raise ArgumentError.new binding.erb <<~END
+            Prop default Proc must take no params or only required keywords
+            ({Proc#arity} of 0 or 1).
+            
+            Default to prop <%= full_name %> has arity <%= default.arity %>.
+            
+          END
+        end
+      
+      elsif !default.frozen?
         raise ArgumentError.new binding.erb <<-END
           Non-proc default values must be frozen
         
@@ -195,13 +282,21 @@ class NRSER::Meta::Props::Prop
   # Instance Methods
   # ============================================================================
   
-  # Used by the {NRSER::Meta::Props::ClassMethods.prop} "macro" method to
+  def names
+    [name, *aliases]
+  end
+  
+  
+  # Used by the {NRSER::Props::Props::ClassMethods.prop} "macro" method to
   # determine if it should create a reader method on the propertied class.
   # 
   # @return [Boolean]
   #   `true` if a reader method should be created for the prop value.
   # 
-  def create_reader?
+  def create_reader? name
+    # If the options was explicitly provided then return that
+    return @reader unless @reader.nil?
+    
     # Always create readers for primary props
     return true if primary?
     
@@ -216,7 +311,7 @@ class NRSER::Meta::Props::Prop
   end # #create_reader?
   
   
-  # Used by the {NRSER::Meta::Props::ClassMethods.prop} "macro" method to
+  # Used by the {NRSER::Props::Props::ClassMethods.prop} "macro" method to
   # determine if it should create a writer method on the propertied class.
   # 
   # Right now, we don't create writers, but we will probably make them an
@@ -225,7 +320,13 @@ class NRSER::Meta::Props::Prop
   # @return [Boolean]
   #   Always `false` for the moment.
   # 
-  def create_writer?
+  def create_writer? name
+    return @writer unless @writer.nil?
+    
+    storage_immutable = defined_in.metadata.storage.try( :immutable? )
+    
+    return !storage_immutable unless storage_immutable.nil?
+    
     false
   end # #create_writer?
   
@@ -259,16 +360,37 @@ class NRSER::Meta::Props::Prop
   alias_method :default?, :has_default?
   
   
-  def default
+  # Get the default value for the property given the instance and values.
+  # 
+  # @todo
+  #   This is a shitty hack stop-gap until I really figure our how this should
+  #   work.
+  # 
+  # @param [Hash<Symbol, Object>] values
+  #   Other prop values known at this point, keyed by name.
+  # 
+  # @return [Object]
+  #   Default value.
+  # 
+  # @raise [NameError]
+  #   If the prop doesn't have a default.
+  # 
+  def default **values
     if has_default?
       if Proc === @default
-        @default.call
+        case @default.arity
+        when 0
+          @default.call
+        else
+          kwds = values.slice *deps
+          @default.call **kwds
+        end
       else
         @default
       end
     else
-      raise NameError.new NRSER.squish <<-END
-        Prop #{ self } has no default value.
+      raise NameError.new binding.erb <<-END
+        Prop <%= full_name %> has no default value (and none provided).
       END
     end
   end
@@ -309,100 +431,107 @@ class NRSER::Meta::Props::Prop
   end # #primary?
   
   
-  # @todo Document get method.
+  # Get the value of the prop from an instance.
   # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
+  # @note
+  #   At the moment, values are **not** type-checked when reading. Primary
+  #   values are checked when setting, so they should be ok, but this does
+  #   leave the possibility that props with a {#source} may return values
+  #   that do not satisfy their types... :/
   # 
-  # @return [return_type]
-  #   @todo Document return value.
+  # @param [NRSER::Props] instance
+  #   An instance of {#defined_in}.
+  # 
+  # @return
+  #   Value from the instance's prop value storage (for {#primary?} props)
+  #   or it's {#source}.
   # 
   def get instance
     if source?
       if instance_variable_source?
         instance.instance_variable_get source
       else
-        case source
-        when String, Symbol
-          instance.send source
-        when Proc
-          instance.instance_exec &source
-        else
-          raise TypeError.squished <<-END
-            Expected `Prop#source` to be a String, Symbol or Proc;
-            found #{ source.inspect }
-          END
-        end
+        t.match source,
+          t.or( String, Symbol ),
+            ->( name ) { instance.send name },
+          Proc,
+            ->( block ) { instance.instance_exec &block }
       end
     else
-      values(instance)[name]
+      # Go through the storage engine
+      instance.class.metadata.storage.get instance, self
     end
   end # #get
   
   
-  # @todo Document set method.
+  # Set a value for a the prop on an instance.
   # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
+  # @param [NRSER::Props] instance
+  #   An instance of {#defined_in}.
   # 
-  # @return [return_type]
-  #   @todo Document return value.
+  # @param [*] value
+  #   A value that must satisfy {#type}.
+  # 
+  # @return [nil]
+  # 
+  # @raise [RuntimeError]
+  #   If you try to set a value for a prop that isn't {#primary?}.
+  # 
+  # @raise  (see #check!)
   # 
   def set instance, value
-    type.check( value ) do
-      binding.erb <<-END
-        Value of type <%= value.class.name %> for prop <%= self.full_name %>
-        failed type check.
+    unless primary?
+      raise RuntimeError.new binding.erb <<~END
+        Only {#primary?} props can be set!
         
-        Must satisfy type:
+        Tried to set prop #{ prop.name } to value
         
-            <%= type %>
+            <%= value.pretty_inspect %>
         
-        Given value:
+        in instance
         
-            <%= value.pretty_inspect %>
+            <%= instance.pretty_inspect %>
         
       END
     end
     
-    values(instance)[name] = value
+    instance.class.metadata.storage.put \
+      instance,
+      self,
+      check!( value )
+    
+    nil
   end # #set
   
   
-  # @todo Document set_from_hash method.
+  # Check that a value satisfies the {#type}, raising if it doesn't.
   # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
+  # @param [VALUE] value
+  #   Value to check.
   # 
-  # @return [return_type]
-  #   @todo Document return value.
+  # @return [VALUE]
+  #   `value` arg that was passed in.
   # 
-  def set_from_values_hash instance, **values
-    if values.key? name
-      set instance, values[name]
-    else
-      if default?
-        # set instance, if !default.nil? && default.respond_to?( :dup )
-        #   default.dup
-        # else
-        #   default
-        # end
-        set instance, default
-      else
-        raise TypeError.new binding.erb <<-ERB
-          Prop <%= full_name %> has no default value and no value was provided
-          in values:
-          
-              <%= values.pretty_inspect %>
-          
-          Prop:
-          
-              <%= self.pretty_inspect %>
-          
-        ERB
-      end
+  # @raise [NRSER::Types::CheckError]
+  #   If `value` does not satisfy {#type}.
+  # 
+  def check! value
+    type.check!( value ) do
+      binding.erb <<-END
+        Value of type <%= value.class.safe_name %> for prop <%= self.full_name %>
+        failed type check.
+        
+        Must satisfy type:
+        
+            <%= type %>
+        
+        Given value:
+        
+            <%= value.pretty_inspect %>
+        
+      END
     end
-  end # #set_from_hash
+  end # #check!
   
   
   # Get the "data" value - a basic scalar or structure of hashes, arrays and
@@ -438,7 +567,7 @@ class NRSER::Meta::Props::Prop
   #     -   The `to_data:` proc is called with the property value as the sole
   #         argument and the result is returned as the data.
   # 
-  # @param [NRSER::Meta::Props] instance
+  # @param [NRSER::Props::Props] instance
   #   Instance to get the property value form.
   # 
   # @return [Object]
@@ -474,13 +603,12 @@ class NRSER::Meta::Props::Prop
   end # #to_data
   
   
-  # @todo Document value_from_data method.
+  # Load a value for the prop from "data".
   # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
+  # @param [*] data
   # 
-  # @return [return_type]
-  #   @todo Document return value.
+  # @return [VALUE]
+  #   The prop value to use.
   # 
   def value_from_data data
     value = case @from_data
@@ -498,7 +626,7 @@ class NRSER::Meta::Props::Prop
       # 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
+      @defined_in.send @from_data, data
     
     when Proc
       # The custom `from_data` configuration provides a procedure, which we
@@ -536,30 +664,7 @@ class NRSER::Meta::Props::Prop
   #   a short string describing the instance.
   # 
   def to_s
-    "#<#{ self.class.name } #{ full_name }:#{ type }>"
+    "#<#{ self.class.safe_name } #{ full_name }:#{ type }>"
   end # #to_s
   
-  
-  private
-    
-    # @todo Document values method.
-    # 
-    # @param [type] arg_name
-    #   @todo Add name param description.
-    # 
-    # @return [return_type]
-    #   @todo Document return value.
-    # 
-    def values instance
-      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 \
-        NRSER::Meta::Props::PROP_VALUES_VARIABLE_NAME
-    end # #value
-  
-end # class NRSER::Meta::Props::Prop
+end # class NRSER::Props::Prop