nrser 0.2.2 → 0.3.0

data/lib/nrser/message.rb

@@ -52,7 +52,7 @@ module NRSER
     
     # Name of method the message is for.
     # 
-    # @return [Symbol | String]
+    # @return [Symbol]
     #     
     attr_reader :symbol
 
@@ -83,12 +83,33 @@ module NRSER
     #   Optional block that should be sent.
     # 
     def initialize symbol, *args, &block
-      @symbol = symbol
+      @symbol = symbol.to_sym
       @args = args
       @block = block
     end
     
     
+    def options
+      if args.last.is_a? Hash
+        args.last
+      else
+        {}
+      end
+    end
+    
+    
+    def symbolize_options
+      if args.last.is_a? Hash
+        self.class.new \
+          symbol,
+          *args[0..-2],
+          args.last.sym_keys
+      else
+        self
+      end
+    end
+    
+    
     # Creates a {Proc} that accepts a single `receiver` argument and calls
     # {#sent_to} on it, allowing messages to be used via the `&` operator
     # in `map`, etc.
@@ -114,7 +135,7 @@ module NRSER
     end
     
     alias_method :to_sender, :to_proc
-
+    
     
     # Send this instance to a receiver object.
     # 

data/lib/nrser/meta/source/location.rb

@@ -0,0 +1,158 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+require 'nrser/props'
+require 'nrser/props/immutable/vector'
+
+
+# Refinements
+# =======================================================================
+
+using NRSER::Types
+
+
+# Declarations
+# =======================================================================
+
+module NRSER::Meta::Source; end
+
+
+# Definitions
+# =======================================================================
+
+# @todo document NRSER::Meta::Source::Location class.
+# 
+class NRSER::Meta::Source::Location < Hamster::Vector
+  
+  # Mixins
+  # ============================================================================
+  
+  include NRSER::Props::Immutable::Vector
+  
+  
+  # Class Methods
+  # ============================================================================
+  
+  # Given an {Enumerable} of {Method} objects, return a {Hash} mapping their
+  # {Method#name} to the method's {NRSER::Meta::Source::Location}.
+  # 
+  # @note
+  #   We map the names instead of the {Method} objects themselves because
+  #   aliases produce two different {Method} objects that `#==` and `#hash`
+  #   the same, preventing them both from being {Hash} keys.
+  # 
+  # @param [Enumerable<Method>] methods
+  #   Methods you want the source locations for.
+  # 
+  # @param [Boolean] only_valid:
+  #   When `true` filter the results to only those that are {#valid?}.
+  # 
+  # @return [Hash<Symbol, NRSER::Meta::Source::Location>]
+  #   Map of method name to their source locations.
+  # 
+  def self.for_methods methods, only_valid: false
+    all = methods.map { |method|
+      [ method.name, NRSER::Meta::Source::Location.new( method ) ]
+    }.to_h
+    
+    if only_valid
+      all.select { |method, location| location.valid? }
+    else
+      all
+    end
+  end # .for_methods
+  
+  
+  # Props
+  # ======================================================================
+  
+  prop  :file, type: t.abs_path?, default: nil, index: 0
+  prop  :line, type: t.pos_int?, default: nil, index: 1
+  
+  
+  # Constructor
+  # ============================================================================
+  
+  # Override to allow argument to be `nil` for when {Method#source_location}
+  # weirdly returns `nil`.
+  # 
+  # @param [(#[] & (#each_pair | #each_index)) | nil ] source
+  #   Source to construct from:
+  #   
+  #   1.  `#[] & (#each_pair | #each_index)`
+  #       1.  Hash-like that responds to `#each_pair` and contains prop
+  #           value sources keyed by their names.
+  #           
+  #           Supports standard propertied class construction.
+  #           
+  #           **Examples:**
+  #           
+  #               {file: '/some/abs/path.rb', line: 88}
+  #               {file: '/some/abs/path.rb', line: nil}
+  #               {file: nil, line: 88}
+  #               {file: nil, line: nil}
+  #               {}
+  #           
+  #       2.  Array-like that responds to `#each_index` and contains prop
+  #           values sources indexed by their non-negative integer indexes.
+  #           
+  #           Supports the output of {Method#source_location}.
+  #           
+  #           **Examples:**
+  #           
+  #               ['/some/abs/path.rb', 88]
+  #               ['/some/abs/path.rb', nil]
+  #               [nil, 88]
+  #               [nil, nil]
+  #               []
+  #           
+  #   2.  `nil` - Swapped for `{]` to support times I'm pretty sure I've seen
+  #       {Method#source_location} return strait-up `nil`.
+  #   
+  # 
+  def initialize source
+    source = source.source_location if source.respond_to? :source_location
+    source = {} if source.nil?
+    super source
+  end
+  
+  
+  # Instance Methods
+  # ======================================================================
+  
+  # Do we have a file and a line?
+  # 
+  # Sometimes `#source_location` gives back `nil` values or just `nil`
+  # (in which case we set both {#file} and {#line} to `nil`). I think this
+  # has to do with C extensions and other weirdness.
+  # 
+  # Anyways, this helps you handle it.
+  # 
+  # @return [Boolean]
+  # 
+  def valid?
+    !( file.nil? && line.nil? )
+  end # #valid?
+  
+  
+  # @return [String]
+  #   a short string describing the instance.
+  # 
+  def to_s
+    "#{ file || '???' }:#{ line || '???' }"
+  end # #to_s
+  
+  
+end # class NRSER::Meta::Source::Location

data/lib/nrser/meta.rb

@@ -1,4 +1,4 @@
 module NRSER::Meta; end
 
 require_relative './meta/class_attrs'
-require_relative './meta/props'
+require_relative './meta/source/location'

data/lib/nrser/props/class_methods.rb

@@ -0,0 +1,118 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+require_relative './metadata'
+
+# Refinements
+# =======================================================================
+
+
+# Declarations
+# =======================================================================
+
+module NRSER::Props; end
+
+
+# Definitions
+# =======================================================================
+
+
+# Class method "macros" that are extended in to data classes, providing the
+# declaration interface.
+# 
+module NRSER::Props::ClassMethods
+  
+  include NRSER::Log::Mixin
+  
+  # Get the metadata object for this class, creating it if it doesn't exist.
+  # 
+  # @return [NRSER::Props::Metadata]
+  # 
+  def metadata
+    # TODO  Move into {NRSER::Props::Metadata}?
+    #       
+    unless NRSER::Props::Metadata.has_metadata? self
+      instance_variable_set \
+        NRSER::Props::Metadata::VARIABLE_NAME,
+        NRSER::Props::Metadata.new( self )
+    end
+    
+    NRSER::Props::Metadata.metadata_for self
+  end
+  
+  
+  def props *args, &block
+    metadata.props *args, &block
+  end
+  
+  
+  def prop *args, &block
+    metadata.prop *args, &block
+  end
+  
+  
+  def invariants *args, &block
+    metadata.invariants *args, &block
+  end
+  
+  
+  def invariant *args, &block
+    metadata.invariant *args, &block
+  end
+  
+  
+  # Instantiate from a data hash.
+  # 
+  # @todo
+  #   This needs to be extended to handle prop'd classes nested in
+  #   arrays and hashes... but for the moment, it is what it is.
+  #   
+  #   This *may* have been fixed...?
+  # 
+  # @param [#each_pair] data
+  # 
+  # @return [self]
+  # 
+  # @raise [NRSER::ArgumentError]
+  #   If `data` does not respond to `#each_pair`.
+  # 
+  def from_data data
+    values = {}
+    props = self.props
+    
+    unless data.respond_to? :each_pair
+      raise NRSER::ArgumentError.new \
+        "`data` argument must respond to `#each_pair`",
+        data: data,
+        class: self
+    end
+    
+    data.each_pair do |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
+    end
+    
+    self.new values
+  end # #from_data
+  
+end # module NRSER::Props::ClassMethods

data/lib/nrser/props/immutable/hash.rb

@@ -0,0 +1,111 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Deps
+# -----------------------------------------------------------------------
+require 'hamster'
+
+# Project / Package
+# -----------------------------------------------------------------------
+require_relative '../storage/key'
+
+
+# Declarations
+# =======================================================================
+
+module NRSER::Props::Immutable; end
+
+
+# Definitions
+# =======================================================================
+
+# Mixin for classes that extend {Hamster::Hash} and will use itself as the
+# property value storage.
+# 
+module NRSER::Props::Immutable::Hash
+  
+  # Constants
+  # ==========================================================================
+  
+  STORAGE = NRSER::Props::Storage::Key.new immutable: true, key_type: :name
+  
+  
+  # Module Methods
+  # ======================================================================
+  
+  def self.included base
+    unless base < Hamster::Hash
+      raise binding.erb <<~END
+        This class is only for including in {Hamster::Hash} subclasses!
+      END
+    end
+    
+    base.include NRSER::Props
+    base.metadata.storage STORAGE
+    base.metadata.freeze
+    
+    base.extend ClassMethods
+    base.include InstanceMethods
+  end
+  
+  
+  # Mixin Methods
+  # ======================================================================
+  
+  # Methods mixed in at the class-level.
+  # 
+  module ClassMethods
+    # {Hamster::Hash} uses `.alloc` to quickly create derived instances
+    # when it knows the instance variables. We need to hook into that to
+    # check the prop types.
+    # 
+    # @param (see Hamster::Hash.alloc)
+    # 
+    # @return [Hamster::Hash]
+    #   The new instance, which will be of the propertied subclass of
+    #   {Hamster::Hash}.
+    # 
+    # @raise [TypeError]
+    #   If the prop values of the new vector don't satisfy the prop types.
+    # 
+    def alloc *args
+      super( *args ).tap do |new_instance|
+        self.props( only_primary: true ).values.each do |prop|
+          prop.check! new_instance[prop.name]
+        end
+      end
+    end
+  end # module ClassMethods
+  
+  module InstanceMethods
+    # Constructor
+    # ----------------------------------------------------------------------------
+    
+    # Since including classes are using themselves as storage, we need to tap
+    # into the `#initialize` chain in order to load property values from sources
+    # and pass an {Array} up to the super-method to instantiate the
+    # {Hamster::Hash}.
+    # 
+    def initialize values = {}
+      # Handles things like `[[:x, 1], [:y, 2]]`
+      values = values.to_h unless values.respond_to?( :each_pair )
+      
+      super_values = {}
+      
+      self.class.metadata.each_primary_prop_value_from( values ) { |prop, value|
+        super_values[prop.name] = value
+      }
+      
+      super super_values
+      
+      # Check additional type invariants
+      self.class.invariants.each do |type|
+        type.check self
+      end
+    end # #initialize
+  end
+  
+end # module NRSER::Props::Immutable::Hash

data/lib/nrser/props/immutable/hash_variable.rb

@@ -0,0 +1,82 @@
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+require_relative '../storage/key'
+require_relative '../storage/instance_variable'
+
+
+# Declarations
+# =======================================================================
+
+module NRSER; end
+module NRSER::Props; end
+
+
+# Definitions
+# =======================================================================
+
+# Mix-in to store property values in an immutable {Hamster::Hash} instance
+# in an instance variable.
+# 
+# This is basically an improvement of how the original props implementation
+# worked.
+# 
+module NRSER::Props::Immutable::HashVariable
+  
+  KEY_STORAGE = NRSER::Props::Storage::Key.new immutable: true, key_type: :name
+  
+  INSTANCE_VARIABLE_STORAGE = \
+    NRSER::Props::Storage::InstanceVariable.new sub_storage: KEY_STORAGE
+  
+  
+  # Class Methods
+  # ======================================================================
+  
+  def self.included base
+    base.include NRSER::Props
+    base.metadata.storage INSTANCE_VARIABLE_STORAGE
+    base.metadata.freeze
+  end
+  
+  
+  # Constructor
+  # ======================================================================
+  
+  # Instantiate a new `NRSER::Props::Immutable::Vector`.
+  def initialize_props values = {}
+    prop_values = {}
+    
+    self.class.metadata.each_primary_prop_value_from( values ) { |prop, value|
+      prop_values[prop.name] = value
+    }
+    
+    instance_variable_set self.class.metadata.storage.var_name,
+                          Hamster::Hash.new( values )
+
+    # Check additional type invariants
+    self.class.invariants.each do |type|
+      type.check self
+    end
+  end # #initialize
+  
+end # module NRSER::Props::Immutable::HashVariable
+
+
+# @todo document NRSER::Props::Immutable::HashVariable::Base module.
+class NRSER::Props::Immutable::HashVariable::Base
+  
+  include NRSER::Props::Immutable::HashVariable
+  
+  def initialize values = {}
+    initialize_props values
+  end
+  
+end # class NRSER::Props::Immutable::HashVariable::Base

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

@@ -0,0 +1,48 @@
+# Requirements
+# =======================================================================
+
+# Project / Package
+# -----------------------------------------------------------------------
+require_relative '../../props'
+require_relative '../storage/key'
+require_relative '../storage/instance_variables'
+
+
+# Definitions
+# =======================================================================
+
+# Mix-in to store property values in instance variables of the same name.
+# 
+module NRSER::Props::Immutable::InstanceVariables
+  
+  STORAGE = NRSER::Props::Storage::InstanceVariables.new immutable: true
+  
+  
+  # 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

data/lib/nrser/props/immutable/vector.rb

@@ -0,0 +1,107 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Deps
+# -----------------------------------------------------------------------
+require 'hamster'
+
+# Project / Package
+# -----------------------------------------------------------------------
+require_relative '../storage/key'
+
+
+# Declarations
+# =======================================================================
+
+module NRSER::Props::Immutable; end
+
+
+# Definitions
+# =======================================================================
+
+# Mixin for classes that extend {Hamster::Vector} and will use itself as the
+# property value storage, requiring that property keys be non-negative
+# integers.
+# 
+module NRSER::Props::Immutable::Vector
+  
+  # Constants
+  # ==========================================================================
+  
+  STORAGE = NRSER::Props::Storage::Key.new immutable: true, key_type: :index
+  
+  
+  # Module Methods
+  # ======================================================================
+  
+  def self.included base
+    unless base < Hamster::Vector
+      raise binding.erb <<~END
+        This class is only for including in {Hamster::Vector} subclasses!
+      END
+    end
+    
+    base.include NRSER::Props
+    base.metadata.storage STORAGE
+    base.metadata.freeze
+    
+    base.extend ClassMethods
+  end
+  
+  
+  # Mixin Methods
+  # ======================================================================
+  
+  # Methods mixed in at the class-level.
+  # 
+  module ClassMethods
+    # {Hamster::Vector} uses `.alloc` to quickly create derived instances
+    # when it knows the instance variables. We need to hook into that to
+    # check the prop types.
+    # 
+    # @param (see Hamster::Vector.alloc)
+    # 
+    # @return [Hamster::Vector]
+    #   The new instance, which will be of the propertied subclass of
+    #   {Hamster::Vector}.
+    # 
+    # @raise [TypeError]
+    #   If the prop values of the new vector don't satisfy the prop types.
+    # 
+    def alloc *args
+      super( *args ).tap do |new_instance|
+        self.props( only_primary: true ).each_value do |prop|
+          prop.check! new_instance[prop.index]
+        end
+      end
+    end
+  end # module ClassMethods
+  
+  
+  # Constructor
+  # ----------------------------------------------------------------------------
+  
+  # Since including classes are using themselves as storage, we need to tap
+  # into the `#initialize` chain in order to load property values from sources
+  # and pass an {Array} up to the super-method to instantiate the
+  # {Hamster::Vector}.
+  # 
+  def initialize values = {}
+    super_values = []
+    
+    self.class.metadata.each_primary_prop_value_from( values ) { |prop, value|
+      super_values[prop.index] = value
+    }
+    
+    super super_values
+    
+    # Check additional type invariants
+    self.class.invariants.each do |type|
+      type.check self
+    end
+  end # #initialize
+  
+end # module NRSER::Props::Immutable::Vector