nrser 0.2.2 → 0.3.0

data/lib/nrser/props/instance_methods.rb

@@ -0,0 +1,184 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+
+# Refinements
+# =======================================================================
+
+
+# Declarations
+# =======================================================================
+
+module NRSER::Props; end
+
+
+# Definitions
+# =======================================================================
+
+# Instance methods to mix in to classes that include {NRSER::Props}.
+# 
+module NRSER::Props::InstanceMethods
+  
+  # Initialize the properties from a hash.
+  # 
+  # Called from `#initialize` in {NRSER::Props::Base}, but if you just
+  # mix in {NRSER::Props::Props} you need to call it yourself.
+  # 
+  # @param [Hash<(String | Symbol) => Object>] values
+  #   Property values. Keys will be normalized to symbols.
+  # 
+  # @return [nil]
+  # 
+  # def initialize_props source_values
+  #   array = []
+  #   hash = {}
+  # 
+  #   self.class.props(only_primary: true).values.each { |prop|
+  #     value = prop.create_value self, source_values
+  #     case prop.key
+  #     when Integer
+  #       array[key] = value
+  #     when Symbol
+  #       hash[key] = value
+  #     else
+  #       raise "SHOULD NEVER HAPPEN, prop.key: #{ prop.pretty_inspect }"
+  #     end
+  #   }
+  # 
+  #   # TODO  Now trigger all eager defaults (check prop getting trigger
+  #   #       correctly)
+  # 
+  #   # Check additional type invariants
+  #   self.class.invariants.each do |type|
+  #     type.check self
+  #   end
+  # 
+  #   nil
+  # end # #initialize_props
+  
+  
+  # @param [Proc<(KEY, CURRENT, UPDATE) => VALUE>] &block
+  #   Optional block to handle conflicts.
+  # 
+  def merge other, &block
+    self.class.new \
+      self.to_h( only_primary: true ).
+      merge( other.symbolize_keys, &block )
+  end
+  
+  
+  def dup
+    self.class.new \
+      self.to_h( only_primary: true )
+  end
+  
+  
+  # Create a new hash with property names mapped to values.
+  # 
+  # @param [Boolean] only_own:
+  #   When `true`, don't include parent properties.
+  # 
+  # @param [Boolean] only_primary:
+  #   When `true`, don't include sourced properties.
+  # 
+  # @return [Hash<Symbol, Object>]
+  #   Map of prop names to values.
+  # 
+  def to_h only_own: false, only_primary: false, compact: true
+    hash = self.class.
+      props(only_own: only_own, only_primary: only_primary).
+      transform_values { |prop| prop.get self }
+    
+    hash.compact! if compact
+    
+    hash
+  end # #to_h
+  
+  
+  # Create a "data" representation suitable for transport, storage, etc.
+  # 
+  # The result is meant to consist of only basic data types and structures -
+  # strings, numbers, arrays, hashes, datetimes, etc... though it depends on
+  # any custom objects it encounters correctly responding to `#to_data` for
+  # this to happen (as is implemented from classes that mix in Props here).
+  # 
+  # Prop names are converted to strings (from symbols) since though YAML
+  # supports symbol values, they have poor portability across languages,
+  # and they mean the same thing in this situation.
+  # 
+  # @param [Boolean] only_own:
+  #   When `true`, don't include parent properties.
+  # 
+  # @param [Boolean] only_primary:
+  #   When `true`, don't include sourced properties.
+  # 
+  # @param [Boolean] add_class:
+  #   Add a special key with the class' name as the value.
+  # 
+  # @param [String] class_key:
+  #   Name for special class key.
+  # 
+  # @return [Hash<String, *>]
+  #   Map of property names as strings to their "data" value, plus the special
+  #   class identifier key and value, if requested.
+  # 
+  def to_data only_own: false,
+              only_primary: false,
+              add_class: true,
+              class_key: '__class__',
+              compact: true
+              # class_key: NRSER::Props::DEFAULT_CLASS_KEY
+              
+    hash = self.class.props(only_own: only_own, only_primary: only_primary).
+      map { |name, prop|
+        [name.to_s, prop.to_data(self)]
+      }.
+      to_h
+    
+    hash.compact! if compact
+    hash[class_key] = self.class.safe_name if add_class
+    
+    hash
+  end # #to_data
+  
+  
+  # Language Inter-Op
+  # ---------------------------------------------------------------------
+  
+  # Get a JSON {String} encoding the instance's data.
+  # 
+  # @param [Array] *args
+  #   I really don't know. `#to_json` takes at last one argument, but I've
+  #   had trouble finding a spec for it :/
+  # 
+  # @return [String]
+  # 
+  def to_json *args
+    to_data.to_json *args
+  end # #to_json
+  
+  
+  # Get a YAML {String} encoding the instance's data.
+  # 
+  # @param [Array] *args
+  #   I really don't know... whatever {YAML.dump} sends to it i guess.
+  # 
+  # @return [String]
+  #   
+  def to_yaml *args
+    to_data.to_yaml *args
+  end
+  
+end # module NRSER::Props::ClassMethods

data/lib/nrser/props/metadata.rb

@@ -0,0 +1,359 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+require 'nrser/refinements/types'
+
+require 'nrser/graph/tsorter'
+
+require_relative './prop'
+
+
+# Refinements
+# =======================================================================
+
+using NRSER::Types
+
+
+# Declarations
+# =======================================================================
+
+module NRSER::Props; end
+
+
+# Definitions
+# =======================================================================
+
+# @todo document NRSER::Props::ClassMetadata class.
+class NRSER::Props::Metadata
+  
+  # Constants
+  # ======================================================================
+  
+  VARIABLE_NAME = :@__NRSER_metadata__
+  
+  
+  # Class Methods
+  # ======================================================================
+  
+  # @todo Document has_metadata? method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def self.has_metadata? klass
+    klass.instance_variable_defined? VARIABLE_NAME
+  end # .has_metadata?
+  
+  
+  def self.metadata_for klass
+    klass.instance_variable_get VARIABLE_NAME
+  end
+  
+  
+  # Attributes
+  # ======================================================================
+  
+  
+  # Constructor
+  # ======================================================================
+  
+  # Instantiate a new `NRSER::Props::ClassMetadata`.
+  def initialize klass
+    @klass = klass
+    @props = {}
+    @invariants = Set.new
+    @storage = nil
+  end # #initialize
+  
+  
+  # Instance Methods
+  # ======================================================================
+  
+  def superclass_has_metadata?
+    @klass.superclass.respond_to? :metadata
+  end
+  
+  
+  def superclass_metadata
+     @klass.superclass.metadata
+  end
+  
+  
+  def get_prop name
+    name = name.to_s.to_sym unless name.is_a?( Symbol )
+    
+    return @props[name] if @props.key?( name )
+    
+    if superclass_has_metadata?
+      superclass_metadata.get_prop name
+    else
+      nil
+    end
+  end
+  
+  alias_method :[], :get_prop
+  
+  
+  # @todo
+  #   Cache / optimize
+  # 
+  def prop_names only_own: false, only_primary: false
+    Set.new props( only_own: only_own, only_primary: only_primary ).keys
+  end
+  
+  
+  # Get a map of property names to property instances.
+  # 
+  # @param [Boolean] only_own:
+  #   Don't include super-class properties.
+  # 
+  # @param [Boolean] only_primary:
+  #   Don't include properties that have a {NRSER::Props::Prop#source}.
+  # 
+  # @return [Hash{ Symbol => NRSER::Props::Prop }]
+  #   Hash mapping property name to property instance.
+  # 
+  def props only_own: false, only_primary: false
+    result = if !only_own && superclass_has_metadata?
+      superclass_metadata.props only_own: only_own,
+                                only_primary: only_primary
+    else
+      {}
+    end
+    
+    if only_primary
+      @props.each {|name, prop| result[name] = prop if prop.primary? }
+    else
+      result.merge! @props
+    end
+    
+    result
+  end # #props
+  
+  
+  # Define a property.
+  # 
+  # @param [Symbol] name
+  #   The name of the property.
+  # 
+  # @param [Hash{ Symbol => Object }] **opts
+  #   Constructor options for {NRSER::Props::Prop}.
+  # 
+  # @return [NRSER::Props::Prop]
+  #   The newly created prop, thought you probably don't need it (it's
+  #   already all bound up on the class at this point), but why not?
+  # 
+  def prop name, **opts
+    t.non_empty_sym.check! name
+    
+    if @props.key? name
+      raise ArgumentError.new binding.erb <<~END
+        Prop <%= name.inspect %> already set for <%= @klass %>:
+        
+            <%= @props[name].inspect %>
+      END
+    end
+    
+    prop = NRSER::Props::Prop.new @klass, name, **opts
+    @props[name] = prop
+    
+    prop.names.each do |name|
+      if prop.create_reader? name
+        @klass.class_eval do
+          define_method name do
+            prop.get self
+          end
+        end
+      end
+      
+      if prop.create_writer? name
+        @klass.class_eval do
+          define_method "#{ name }=" do |value|
+            prop.set self, value
+          end
+        end
+      end
+    end
+    
+    prop
+  end # #prop
+  
+  
+  # Check primary prop values and fill in defaults, yielding `(Prop, VALUE)`
+  # to the `&block`.
+  # 
+  # Used when initializing instances.
+  # 
+  # @param [#each_pair | #each_index] values
+  #   Collection of prop values iterable by key/value pairs or by indexed
+  #   entries.
+  # 
+  # @param [Proc<(NRSER::Props::Prop, VALUE)>] &block
+  #   Block that will receive primary prop and value pairs.
+  # 
+  # @raise [TypeError]
+  #   If a value is does not satisfy it's {NRSER::Props::Prop#type}.
+  # 
+  # @raise [ArgumentError]
+  #   If `values` doesn't respond to `#each_pair` or `#each_index`.
+  # 
+  # @raise [NameError]
+  #   If a value is not provided for a primary prop and a default can not
+  #   be created.
+  # 
+  # @raise [TSort::Cyclic]
+  #   If any of the primary prop's {NRSER::Props::Prop#deps} for dependency
+  #   cycles.
+  # 
+  def each_primary_prop_value_from values, &block
+    primary_props = props only_primary: true
+    
+    # Normalize values to a `Hash<Symbol, VALUE>` so everything can deal with
+    # one form. Default values will be set here as they're resolved and made
+    # available to subsequent {Prop#default} calls.
+    values_by_name = {}
+    
+    if values.respond_to? :each_pair
+      values.each_pair { |key, value|
+        # Figure out the prop name {Symbol}
+        name = case key
+        when Symbol
+          key
+        when String
+          key.to_sym
+        else
+          key.to_s.to_sym
+        end
+        
+        # If the `name` corresponds to a primary prop set it in the values by
+        # name
+        # 
+        # TODO  Should check that the name is not already set?
+        # 
+        values_by_name[name] = value if primary_props.key? name
+      }
+    elsif values.respond_to? :each_index
+      indexed = []
+      
+      primary_props.each_value do |prop|
+        indexed[prop.index] = prop unless prop.index.nil?
+      end
+      
+      values.each_index { |index|
+        prop = indexed[index]
+        values_by_name[prop.name] = values[index] if prop
+      }
+    else
+      raise ArgumentError.new binding.erb <<~END
+        `source` argument must respond to `#each_pair` or `#each_index`
+        
+        Found:
+        
+            <%= source.pretty_inspect %>
+        
+      END
+    end
+    
+    # Topological sort the primary props by their default dependencies.
+    # 
+    NRSER::Graph::TSorter.new(
+      primary_props.each_value
+    ) { |prop, &on_dep_prop|
+      # 
+      # This block is responsible for receiving a {Prop} and a callback
+      # block and invoking that callback block on each of the prop's
+      # dependencies (if any).
+      # 
+      prop.deps.each { |name|
+        if primary_props.key? name
+          on_dep_prop.call primary_props[name]
+        else
+          raise RuntimeError.new binding.erb <<~END
+            Property <%= prop.full_name %> depends on prop `<%= name %>`,
+            but no primary prop with that name could be found!
+          END
+        end
+      }
+    }.tsort_each do |prop|
+      # {Prop} instances will now be yielded in an order that allows any
+      # inter-dependencies to be resolved (as long as there weren't dependency
+      # cycles, which {NRSER::Graph::TSorter} will raise if it finds)
+      
+      # If we have a value for the prop, just check that
+      if values_by_name.key? prop.name
+        prop.check! values_by_name[prop.name]
+      else
+        # Otherwise, get the default value, providing the values we already
+        # know in case the default is a {Proc} that needs some of them.
+        # 
+        # We set that value in `values_by_name` so that subsequent
+        # {Prop#default} calls can use it.
+        # 
+        values_by_name[prop.name] = prop.default **values_by_name
+      end
+      
+      # Yield the {Prop} and it's value back to the `&block`
+      block.call prop, values_by_name[prop.name]
+    end # .tsort_each
+  end # #each_primary_prop_value_from
+  
+  
+  def invariants only_own: false
+    result = if !only_own && superclass_has_metadata?
+      superclass_metadata.invariants only_own: false
+    else
+      Set.new
+    end
+    
+    result + @invariants
+  end
+  
+  
+  def invariant type
+    @invariants.add type
+  end
+  
+  
+  def default_storage
+    if superclass_has_metadata?
+      superclass_metadata.storage
+    else
+      @storage = NRSER::Props::Storage::InstanceVariable.new
+    end
+  end
+  
+  
+  def storage value = nil
+    if value.nil?
+      if @storage.nil?
+        default_storage
+      else
+        @storage
+      end
+    else
+      @storage = value
+    end
+  end
+  
+  
+  def freeze
+    super()
+  
+    if  superclass_has_metadata? &&
+        !superclass_metadata.frozen?
+      superclass_metadata.freeze
+    end
+    
+  end
+  
+  
+end # class NRSER::Props::ClassMetadata

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

@@ -0,0 +1,60 @@
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+require_relative '../../props'
+require_relative '../storage/key'
+require_relative '../storage/instance_variables'
+
+
+# Declarations
+# ========================================================================
+
+module NRSER::Props::Mutable; end
+
+
+# Definitions
+# =======================================================================
+
+# Mix-in to store property values in instance variables of the same name.
+# 
+module NRSER::Props::Mutable::InstanceVariables
+  
+  STORAGE = NRSER::Props::Storage::InstanceVariables.new immutable: false
+  
+  
+  # Class Methods
+  # ======================================================================
+  
+  def self.included base
+    base.include NRSER::Props
+    base.metadata.storage STORAGE
+    base.metadata.freeze
+  end
+  
+  
+  # Instance Methods
+  # ======================================================================
+  
+  # Since the {NRSER::Props::Immutable::InstanceVariables} mix-in does *not*
+  # need to tap into the initialize chain,
+  # 
+  def initialize_props values = {}
+    self.class.metadata.each_primary_prop_value_from( values ) { |prop, value|
+      instance_variable_set "@#{ prop.name }", value
+    }
+    
+    # Check additional type invariants
+    self.class.invariants.each do |type|
+      type.check self
+    end
+  end # #initialize_props
+  
+end # module NRSER::Props::Immutable