nrser 0.2.2 → 0.3.0

data/lib/nrser/meta/props.rb

@@ -1,357 +0,0 @@
-# Refinements
-# =======================================================================
-
-using NRSER
-using NRSER::Types
-
-
-# Definitions
-# =======================================================================
-
-module NRSER::Meta::Props
-  DEFAULT_CLASS_KEY = '__class__';
-  
-  PROPS_VARIABLE_NAME = :@__NRSER_props
-  PROP_VALUES_VARIABLE_NAME = :@__NRSER_prop_values
-  
-  
-  # Module Methods (Utilities)
-  # =====================================================================
-  # 
-  # These are *NOT* mixed in to including classes, and must be accessed
-  # via `NRSER::Meta::Props.<method_name>`.
-  # 
-  # They're utilities that should only really need to be used internally.
-  # 
-  
-  
-  # @todo Document get_props_ref method.
-  # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
-  # 
-  # @return [return_type]
-  #   @todo Document return value.
-  # 
-  def self.get_props_ref klass
-    unless klass.instance_variable_defined? PROPS_VARIABLE_NAME
-      klass.instance_variable_set PROPS_VARIABLE_NAME, {}
-    end
-    
-    klass.instance_variable_get PROPS_VARIABLE_NAME
-  end # .get_props_ref
-  
-  
-  # Instantiate a class from a data hash. The hash must contain the
-  # `__class__` key and the target class must be loaded already.
-  # 
-  # **WARNING**
-  # 
-  # I'm sure this is all-sorts of unsafe. Please don't ever think this is
-  # reasonable to use on untrusted data.
-  # 
-  # @param [Hash<String, Object>] data
-  #   Data hash to load from.
-  # 
-  # @param
-  # 
-  # @return [NRSER::Meta::Props]
-  #   Instance of a propertied class.
-  # 
-  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 binding.erb <<-ERB
-        Data is missing <%= class_key %> key - no idea what class to
-        instantiate.
-        
-        Data:
-        
-            <%= data.pretty_inspect %>
-        
-      ERB
-    end
-    
-    # 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 # .UNSAFE_load_instance_from_data
-  
-  
-  # Hook to extend the including class with {NRSER::Meta::Props:ClassMethods}
-  def self.included base
-    base.extend ClassMethods
-  end
-  
-  
-  # Mixed-In Class Methods
-  # =====================================================================
-  
-  # Methods added to the including *class* via `extend`.
-  # 
-  module ClassMethods
-    
-    # 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::Meta::Props::Prop#source}.
-    # 
-    # @return [Hash{ Symbol => NRSER::Meta::Props::Prop }]
-    #   Hash mapping property name to property instance.
-    # 
-    def props only_own: false, only_primary: false
-      result = if !only_own && superclass.respond_to?(:props)
-        superclass.props only_own: only_own, only_primary: only_primary
-      else
-        {}
-      end
-      
-      own_props = NRSER::Meta::Props.get_props_ref self
-      
-      if only_primary
-        own_props.each {|name, prop|
-          if prop.primary?
-            result[name] = prop
-          end
-        }
-      else
-        result.merge! own_props
-      end
-      
-      result
-    end # #own_props
-    
-    
-    # Define a property.
-    # 
-    # @param [Symbol] name
-    #   The name of the property.
-    # 
-    # @param [Hash{ Symbol => Object }] **opts
-    #   Constructor options for {NRSER::Meta::Props::Prop}.
-    # 
-    # @return [NRSER::Meta::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
-      ref = NRSER::Meta::Props.get_props_ref self
-      
-      t.sym.check name
-      
-      if ref.key? name
-        raise ArgumentError.new NRSER.squish <<-END
-          Prop #{ name.inspect } already set for #{ self }:
-          #{ ref[name].inspect }
-        END
-      end
-      
-      prop = Prop.new self, name, **opts
-      ref[name] = prop
-      
-      if prop.create_reader?
-        class_eval do
-          define_method prop.name do
-            prop.get self
-          end
-        end
-      end
-      
-      if prop.create_writer?
-        class_eval do
-          define_method "#{ prop.name }=" do |value|
-            prop.set self, value
-          end
-        end
-      end
-      
-      prop
-    end # #prop
-    
-    
-    # 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.
-    # 
-    # @param [Hash<String, Object>] data
-    # 
-    # @return [self]
-    # 
-    def from_data data
-      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
-    
-    
-  end # module ClassMethods
-  
-  
-  # Mixed-In Instance Methods
-  # =====================================================================
-  
-  # @todo Document initialize_props method.
-  # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
-  # 
-  # @return [return_type]
-  #   @todo Document return value.
-  # 
-  def initialize_props values
-    self.class.props(only_primary: true).each { |name, prop|
-      prop.set_from_values_hash self, values
-    }
-    
-    # TODO  Now trigger all eager defaults (check prop getting trigger 
-    #       correctly)
-  end # #initialize_props
-  
-  
-  def merge overrides = {}
-    self.class.new(
-      self.to_h(only_primary: true).merge(overrides.symbolize_keys)
-    )
-  end
-  
-  
-  # @todo Document to_h method.
-  # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
-  # 
-  # @return [Hash<Symbol, Object>]
-  #   @todo Document return value.
-  # 
-  def to_h only_own: false, only_primary: false
-    self.class.
-      props(only_own: only_own, only_primary: only_primary).
-      map_values { |name, prop| prop.get self }
-  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 [type] arg_name
-  #   @todo Add name param description.
-  # 
-  # @return [Hash<String, Object>]
-  #   @todo Document return value.
-  # 
-  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
-      }
-  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 Props
-
-
-# Post-Processing
-# =======================================================================
-
-require_relative './props/prop'
-require_relative './props/base'

data/lib/nrser/refinements/array.rb

@@ -1,133 +0,0 @@
-module NRSER
-  refine ::Array do
-    include NRSER::Ext::Enumerable
-    include NRSER::Ext::Tree
-    
-    
-    # @return [Array]
-    #   new array consisting of all elements after the first (which may be
-    #   none, resulting in an empty array).
-    # 
-    def rest
-      NRSER.rest self
-    end # #rest
-    
-    
-    def extract! &block
-      NRSER.extract_from_array! self, &block
-    end
-    
-    
-    # Calls {NRSER.ellipsis} on `self`.
-    def ellipsis *args
-      NRSER.ellipsis self, *args
-    end
-    
-    
-    # `to_*` Converters
-    # =====================================================================
-    
-    # Checks that length is 2 and returns `self`.
-    # 
-    # @return [Array]
-    #   Array of length 2.
-    # 
-    # @raise [TypeError]
-    #   If length is not 2.
-    # 
-    def to_pair
-      unless length == 2
-        raise TypeError,
-              "Array is not of length 2: #{ self.inspect }"
-      end
-      
-      self
-    end # #to_pair
-    
-    
-    # To Operation Objects
-    # ---------------------------------------------------------------------
-    
-    # Creates a new {NRSER::Message} from the array.
-    # 
-    # @example
-    #   
-    #   message = [:fetch, :x].to_message
-    #   message.send_to x: 'ex', y: 'why?'
-    #   # => 'ex'
-    # 
-    # @return [NRSER::Message]
-    # 
-    def to_message
-      NRSER::Message.new *self
-    end # #to_message
-    
-    alias_method :to_m, :to_message
-    
-    
-    # Create a {Proc} that accepts a single `receiver` and provides this array's
-    # entries as the arguments to `#public_send` (or `#send` if the `publicly`
-    # option is `false`).
-    # 
-    # Equivalent to
-    # 
-    #   to_message.to_proc publicly: boolean
-    # 
-    # @example
-    #   
-    #   [:fetch, :x].sender.call x: 'ex'
-    #   # => 'ex'
-    # 
-    # @param [Boolean] publicly:
-    #   When `true`, uses `#public_send` in liu of `#send`.
-    # 
-    # @return [Proc]
-    # 
-    def to_sender publicly: true
-      to_message.to_proc publicly: publicly
-    end
-    
-    alias_method :sender, :to_sender
-    alias_method :sndr, :to_sender
-    
-    
-    # See {NRSER.chainer}.
-    #
-    def to_chainer publicly: true
-      NRSER.chainer self, publicly: publicly
-    end # #to_chainer
-    
-    alias_method :chainer, :to_chainer
-    alias_method :chnr, :to_chainer
-    
-    
-    # Returns a lambda that calls accepts a single arg and calls `#dig` on it
-    # with the elements of *this* array as arguments.
-    # 
-    # @example
-    #   list = [{id: 1, name: "Neil"}, {id: 2, name: "Mica"}]
-    #   list.to_h_by &[:id].digger
-    #   # =>  {
-    #   #       1 => {id: 1, name: "Neil"},
-    #   #       2 => {id: 2, name: "Mica"},
-    #   #     }
-    # 
-    # @todo
-    #   I wanted to use `#to_proc` so that you could use `&[:id]`, but unary
-    #   `&` doesn't invoke refinements, and I don't really want to monkey-patch
-    #   anything, especially something as core as `#to_proc` and `Array`.
-    # 
-    # @return [Proc]
-    #   Lambda proc that accepts a single argument and calls `#dig` with this
-    #   array's contents as the `#dig` arguments.
-    # 
-    def to_digger
-      NRSER::Message.new( :dig, *self ).to_proc
-    end # #to_digger
-    
-    alias_method :digger, :to_digger
-    alias_method :dggr, :to_digger
-    
-    
-  end # refine ::Array
-end # NRSER

data/lib/nrser/refinements/binding.rb

@@ -1,6 +0,0 @@
-module NRSER
-  # Harness to include {NRSER::Ext::Binding} in {Binding}
-  refine Binding do
-    include NRSER::Ext::Binding
-  end
-end # NRSER

data/lib/nrser/refinements/enumerator.rb

@@ -1,5 +0,0 @@
-module NRSER
-  refine ::Enumerator do
-    include NRSER::Ext::Enumerable
-  end # refine ::Enumerator
-end # NRSER

data/lib/nrser/refinements/exception.rb

@@ -1,35 +0,0 @@
-module NRSER
-  refine Exception do
-    def format
-      NRSER.format_exception self
-    end
-  end
-  
-  refine Exception.singleton_class do
-  
-    # Create a new instance from the squished message.
-    # 
-    # See {NRSER.squish}.
-    # 
-    # @param [String] message
-    # 
-    # @return [Exception]
-    # 
-    def squished message
-      new NRSER.squish( message )
-    end
-    
-    # Create a new instance from the dedented message.
-    # 
-    # See {NRSER.dedent}.
-    # 
-    # @param [String] message
-    # 
-    # @return [Exception]
-    # 
-    def dedented message
-      new NRSER.dedent( message )
-    end
-    
-  end # refine Exception.singleton_class
-end # NRSER

data/lib/nrser/refinements/hash.rb

@@ -1,150 +0,0 @@
-module NRSER
-  
-  refine ::Hash do
-    include NRSER::Ext::Enumerable
-    include NRSER::Ext::Tree
-    
-    
-    # See {NRSER.except_keys!}.
-    def except! *keys
-      NRSER.except_keys! self, *keys
-    end
-    
-    alias_method :omit!, :except!
-    
-    
-    # See {NRSER.except_keys}.
-    def except *keys
-      NRSER.except_keys self, *keys
-    end
-    
-    alias_method :omit, :except
-    
-    
-    # See {NRSER.slice_keys}.
-    def slice *keys
-      NRSER.slice_keys self, *keys
-    end
-    
-    
-    # See {NRSER.transform_keys!}
-    def transform_keys! &block
-      return enum_for(:transform_keys!) { size } unless block_given?
-      NRSER.transform_keys! self, &block
-    end
-    
-    
-    # See {NRSER.deep_transform_keys!}
-    def deep_transform_keys! &block
-      return enum_for(:deep_transform_keys!) { size } unless block_given?
-      NRSER.deep_transform_keys! self, &block
-    end
-    
-    alias_method :deep_map_keys!, :deep_transform_keys!
-    alias_method :map_keys_r!,    :deep_transform_keys!
-    alias_method :deep_rekey!,    :deep_transform_keys!
-    alias_method :rekey_r!,       :deep_transform_keys!
-    
-    
-    # See {NRSER.transform_keys}
-    def transform_keys &block
-      return enum_for(:transform_keys) { size } unless block_given?
-      NRSER.transform_keys self, &block
-    end
-    
-    
-    # See {NRSER.deep_transform_keys}
-    def deep_transform_keys &block
-      return enum_for(:deep_transform_keys) { size } unless block_given?
-      NRSER.deep_transform_keys self, &block
-    end
-    
-    alias_method :deep_map_keys, :deep_transform_keys
-    alias_method :map_keys_r,    :deep_transform_keys
-    alias_method :deep_rekey,    :deep_transform_keys
-    alias_method :rekey_r,       :deep_transform_keys
-    
-    
-    # See {NRSER.symbolize_keys!}
-    def symbolize_keys!
-      NRSER.symbolize_keys! self
-    end
-    
-    alias_method :sym_keys!, :symbolize_keys!
-    
-    
-    # See {NRSER.symbolize_keys}
-    def symbolize_keys
-      NRSER.symbolize_keys self
-    end
-    
-    alias_method :sym_keys, :symbolize_keys
-    
-    
-    # See {NRSER.stringify_keys!}
-    def stringify_keys!
-      NRSER.stringify_keys! self
-    end
-    
-    alias_method :str_keys!, :stringify_keys!
-    
-    
-    # See {NRSER.stringify_keys}
-    def stringify_keys
-      NRSER.stringify_keys self
-    end
-    
-    alias_method :str_keys, :stringify_keys
-    
-    
-    # See {NRSER.map_hash_keys}
-    def map_keys &block
-      NRSER.map_keys self, &block
-    end
-    
-    
-    # See {NRSER.bury!}
-    def bury! key_path,
-              value,
-              parsed_key_type: :guess,
-              clobber: false
-      NRSER.bury! self,
-                  key_path,
-                  value,
-                  parsed_key_type: parsed_key_type,
-                  clobber: clobber
-    end
-    
-    
-    # Checks that `self` contains a single key/value pair (`#length` of 1)
-    # and returns it as an array of length 2.
-    # 
-    # @return [Array]
-    #   Array of length 2.
-    # 
-    # @raise [TypeError]
-    #   If `self` has more than one key/value pair.
-    # 
-    def to_pair
-      unless length == 1
-        raise TypeError,
-              "Hash has more than one pair: #{ self.inspect }"
-      end
-      
-      first
-    end
-    
-    
-    # See {NRSER.deep_merge}
-    def deep_merge other_hash, &block
-      NRSER.deep_merge self, other_hash, &block
-    end
-    
-    
-    # See {NRSER.deep_merge!}
-    def deep_merge! other_hash, &block
-      NRSER.deep_merge! self, other_hash, &block
-    end
-    
-  end # refine ::Hash
-end # NRSER

data/lib/nrser/refinements/module.rb

@@ -1,5 +0,0 @@
-module NRSER
-  refine Module do
-    include NRSER::Ext::Module
-  end
-end