nrser 0.0.19 → 0.0.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f34385ea491972db4f43263773d9e9655ddabf85
-  data.tar.gz: af6e560b27729d1d16e8aa007515eb2d4eee354f
+  metadata.gz: 01fe1d56c4df90623c6407128463f67ca2e65426
+  data.tar.gz: 0b1dfcb6cdd036647526482901cffe7e652cf189
 SHA512:
-  metadata.gz: 8b9e68cefda2494539cd0f44efdee84ce70ddba6bbaccbe989e1cae0de30356cfbac0c5ede7df901489317a970cc3bec8dd38a720654344497e7dc3b47e66d3f
-  data.tar.gz: c400d4be2fed9d8120453f049dd86904c9bd8a2283525dee076318054d690f66b36f838453ef5a0c650f37323c57df86ee0acf33bf303893959f02d27c8342cc
+  metadata.gz: af6cf0974b665d43b2b56a5fecbc1c44c2014f2aeb031eb3b831d599d55003a5d83ba6a6cdf604b34fc64700a6f713a96c8d9b69e51f550a3008449ee2d5de79
+  data.tar.gz: e368146e2161490ed4a831063e6a79540e084c45c52a685801776b759c43cf37e5d679bad11bbe2b22fd8f2d78012276f73843a0afa0a14d54226bccd138b8ca

data/lib/nrser/hash.rb

@@ -238,22 +238,59 @@ module NRSER
   # @see http://www.rubydoc.info/gems/activesupport/5.1.3/Hash:symbolize_keys!
   # 
   # @param [Hash] hash
-  #   Hash to mutate.
   # 
-  # @return [return_type]
-  #   @todo Document return value.
+  # @return [Hash]
   # 
   def self.symbolize_keys! hash
     transform_keys!(hash) { |key| key.to_sym rescue key }
   end # .symbolize_keys!
   
   
-  
+  # Returns a new hash with all keys that respond to `#to_sym` converted to
+  # symbols.
+  # 
+  # Lifted from ActiveSupport.
+  # 
+  # @see http://www.rubydoc.info/gems/activesupport/5.1.3/Hash:symbolize_keys
+  # 
+  # @param [Hash] hash
+  # 
+  # @return [Hash]
+  # 
   def self.symbolize_keys hash
     # File 'lib/active_support/core_ext/hash/keys.rb', line 54
     transform_keys(hash) { |key| key.to_sym rescue key }
   end
   
+  
+  # Converts all keys into strings by calling `#to_s` on them. **Mutates the
+  # hash.**
+  # 
+  # Lifted from ActiveSupport.
+  # 
+  # @param [Hash] hash
+  # 
+  # @return [Hash<String, *>]
+  # 
+  def self.stringify_keys! hash
+    transform_keys! hash, &:to_s
+  end
+  
+  
+  # Returns a new hash with all keys transformed to strings by calling `#to_s`
+  # on them.
+  # 
+  # Lifted from ActiveSupport.
+  # 
+  # @param [Hash] hash
+  # 
+  # @return [Hash<String, *>]
+  # 
+  def self.stringify_keys hash
+    transform_keys hash, &:to_s
+  end
+  
+  
   # Lifted from ActiveSupport.
   # 
   # @see http://www.rubydoc.info/gems/activesupport/5.1.3/Hash:slice

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

@@ -0,0 +1,212 @@
+require 'nrser/no_arg'
+
+require 'nrser/refinements'
+require 'nrser/refinements/types'
+
+using NRSER::Types
+
+module NRSER 
+module Meta
+module Props
+  
+class Prop
+  attr_accessor :defined_in,
+                :name,
+                :type,
+                :source
+  
+  
+  def initialize  defined_in,
+                  name,
+                  type: t.any,
+                  default: NRSER::NO_ARG,
+                  source: nil
+    
+    @defined_in = defined_in
+    @name = name
+    @type = t.make type
+    @source = source
+    @default = default
+    
+    if @source.nil?
+      @instance_variable_source = false
+    else
+      source_str = source.to_s
+      @instance_variable_source = source_str[0] == '@'
+    end
+  end
+  
+  
+  # @todo Document default? method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def default?
+    @default != NRSER::NO_ARG
+  end # #default?
+  
+  
+  def default
+    if default?
+      @default
+    else
+      raise NameError.new NRSER.squish <<-END
+        Prop #{ self } has no default value.
+      END
+    end
+  end
+  
+  
+  # @todo Document source? method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def source?
+    !@source.nil?
+  end # #source?
+  
+  
+  # @todo Document instance_variable_source? method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def instance_variable_source?
+    @instance_variable_source
+  end # #instance_variable_source?
+  
+  
+  # @todo Document primary? method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def primary?
+    !source?
+  end # #primary?
+  
+  
+  # @todo Document get method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def get instance
+    if source?
+      if instance_variable_source?
+        instance.instance_variable_get source
+      else
+        instance.send source
+      end
+    else
+      values(instance)[name]
+    end
+  end # #get
+  
+  
+  # @todo Document set method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @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 }
+      END
+    end
+    
+    values(instance)[name] = value
+  end # #set
+  
+  
+  
+  # @todo Document set_from_hash method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def set_from_values_hash instance, **values
+    if values.key? name
+      set instance, values[name]
+    else
+      if default?
+        set instance, default.dup
+      else
+        raise TypeError.new NRSER.squish <<-END
+          Prop #{ name } has no default value and no value was provided in
+          values #{ values.inspect }.
+        END
+      end
+    end
+  end # #set_from_hash
+  
+  
+  
+  # @todo Document to_data method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def to_data instance
+    value = get instance
+    
+    if value.respond_to? :to_data
+      value.to_data
+    else
+      value
+    end
+  end # #to_data
+  
+  
+  
+  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? PROP_VALUES_VARIABLE_NAME
+        instance.instance_variable_set PROP_VALUES_VARIABLE_NAME, {}
+      end
+      
+      instance.instance_variable_get PROP_VALUES_VARIABLE_NAME
+    end # #value
+  
+end # class Prop
+  
+end # module Props
+end # module Meta
+end # module NRSER

data/lib/nrser/meta/props.rb

@@ -1,189 +1,28 @@
-module NRSER 
-module Meta 
+require 'pp'
+
+require 'nrser/refinements'
+require 'nrser/refinements/types'
 
-T = NRSER::Types
+using NRSER
+using NRSER::Types
+
+module NRSER 
+module Meta
 
-# 
 module Props
+  CLASS_KEY = '__class__';
   PROPS_VARIABLE_NAME = :@__NRSER_props
   PROP_VALUES_VARIABLE_NAME = :@__NRSER_prop_values
   
-  class Prop
-    attr_accessor :defined_in,
-                  :name,
-                  :type,
-                  :source
-    
-    
-    def initialize  defined_in,
-                    name,
-                    type: T.any,
-                    default: NRSER::NO_ARG,
-                    source: nil
-      
-      @defined_in = defined_in
-      @name = name
-      @type = NRSER::Types.make type
-      @source = source
-      @default = default
-      
-      if @source.nil?
-        @instance_variable_source = false
-      else
-        source_str = source.to_s
-        @instance_variable_source = source_str[0] == '@'
-      end
-    end
-    
-    
-    # @todo Document default? method.
-    # 
-    # @param [type] arg_name
-    #   @todo Add name param description.
-    # 
-    # @return [return_type]
-    #   @todo Document return value.
-    # 
-    def default?
-      @default != NRSER::NO_ARG
-    end # #default?
-    
-    
-    def default
-      if default?
-        @default
-      else
-        raise NameError.new NRSER.squish <<-END
-          Prop #{ self } has no default value.
-        END
-      end
-    end
-    
-    
-    # @todo Document source? method.
-    # 
-    # @param [type] arg_name
-    #   @todo Add name param description.
-    # 
-    # @return [return_type]
-    #   @todo Document return value.
-    # 
-    def source?
-      !@source.nil?
-    end # #source?
-    
-    
-    # @todo Document instance_variable_source? method.
-    # 
-    # @param [type] arg_name
-    #   @todo Add name param description.
-    # 
-    # @return [return_type]
-    #   @todo Document return value.
-    # 
-    def instance_variable_source?
-      @instance_variable_source
-    end # #instance_variable_source?
-    
-    
-    # @todo Document primary? method.
-    # 
-    # @param [type] arg_name
-    #   @todo Add name param description.
-    # 
-    # @return [return_type]
-    #   @todo Document return value.
-    # 
-    def primary?
-      !source?
-    end # #primary?
-    
-    
-    # @todo Document get method.
-    # 
-    # @param [type] arg_name
-    #   @todo Add name param description.
-    # 
-    # @return [return_type]
-    #   @todo Document return value.
-    # 
-    def get instance
-      if source?
-        if instance_variable_source?
-          instance.instance_variable_get source
-        else
-          instance.send source
-        end
-      else
-        values(instance)[name]
-      end
-    end # #get
-    
-    
-    # @todo Document set method.
-    # 
-    # @param [type] arg_name
-    #   @todo Add name param description.
-    # 
-    # @return [return_type]
-    #   @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 }
-        END
-      end
-      
-      values(instance)[name] = value
-    end # #set
-    
-    
-    
-    # @todo Document set_from_hash method.
-    # 
-    # @param [type] arg_name
-    #   @todo Add name param description.
-    # 
-    # @return [return_type]
-    #   @todo Document return value.
-    # 
-    def set_from_values_hash instance, **values
-      if values.key? name
-        set instance, values[name]
-      else
-        if default?
-          set instance, default.dup
-        else
-          raise TypeError.new NRSER.squish <<-END
-            Prop #{ name } has no default value and no value was provided in
-            values #{ values.inspect }.
-          END
-        end
-      end
-    end # #set_from_hash
-    
-    
-    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? PROP_VALUES_VARIABLE_NAME
-          instance.instance_variable_set PROP_VALUES_VARIABLE_NAME, {}
-        end
-        
-        instance.instance_variable_get PROP_VALUES_VARIABLE_NAME
-      end # #value
-    
-  end # class Prop
+  
+  # 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.
@@ -203,8 +42,50 @@ module Props
   end # .get_props_ref
   
   
-  module ClassMethods
+  # 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
+  # 
+  # @return [Object]
+  #   @todo Document return value.
+  # 
+  # 
+  # 
+  def self.from_data data
+    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.
+        
+        #{ data.pretty_inspect }
+      END
+    end
+    
+    class_name = t.str.check data[CLASS_KEY]
+    klass = class_name.to_const
+    klass.from_data data
+  end # .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
     
     # @todo Document props method.
     # 
@@ -214,16 +95,16 @@ module Props
     # @return [return_type]
     #   @todo Document return value.
     # 
-    def props own: false, primary: false
-      result = if !own && superclass.respond_to?(:props)
-        superclass.props own: own, primary: primary
+    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 primary
+      if only_primary
         own_props.each {|name, prop|
           if prop.primary?
             result[name] = prop
@@ -248,7 +129,7 @@ module Props
     def prop name, **opts
       ref = NRSER::Meta::Props.get_props_ref self
       
-      T.sym.check name
+      t.sym.check name
       
       if ref.key? name
         raise ArgumentError.new NRSER.squish <<-END
@@ -275,38 +156,27 @@ module Props
     end # #prop
     
     
-    
-    # @todo Document from_h method.
+    # Instantiate from a data hash.
     # 
-    # @param [type] arg_name
-    #   @todo Add name param description.
+    # @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.
     # 
-    # @return [return_type]
-    #   @todo Document return value.
+    # @param [Hash<String, Object>] data
     # 
-    def from_h hash
-      self.new(
-        NRSER.slice_keys(
-          NRSER.symbolize_keys(hash),
-          *self.props(primary: true).keys
-        )
-      )
-    end # #from_h
+    # @return [self]
+    # 
+    def from_data data
+      self.new data.symbolize_keys
+    end # #from_data
+    
     
-      
   end # module ClassMethods
   
   
-  # Extend the including class with {NRSER::Meta::Props:ClassMethods}
-  def self.included base
-    base.extend ClassMethods
-  end
-  
-  
-  # Instance Methods
+  # Mixed-In Instance Methods
   # =====================================================================
   
-  
   # @todo Document initialize_props method.
   # 
   # @param [type] arg_name
@@ -316,26 +186,60 @@ module Props
   #   @todo Document return value.
   # 
   def initialize_props values
-    self.class.props(primary: true).each { |name, prop|
+    self.class.props(only_primary: true).each { |name, prop|
       prop.set_from_values_hash self, values
     }
   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 [return_type]
+  # @return [Hash<Symbol, Object>]
   #   @todo Document return value.
   # 
-  def to_h primary: false, own: false
-    NRSER.map_values(
-      self.class.props own: own, primary: primary
-    ) { |name, prop| prop.get self }
+  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
+    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
+  
   
   # @todo Document to_json method.
   # 
@@ -346,12 +250,12 @@ module Props
   #   @todo Document return value.
   # 
   def to_json *args
-    to_h.to_json *args
+    to_data.to_json *args
   end # #to_json
   
   
   def to_yaml *args
-    to_h.to_yaml *args
+    to_data.to_yaml *args
   end
   
   
@@ -360,4 +264,5 @@ end # module Props
 end # module Meta
 end # module NRSER
 
-require_relative './props/base'
+require_relative './props/prop'
+require_relative './props/base'

data/lib/nrser/refinements/hash.rb

@@ -33,29 +33,44 @@ module NRSER
       NRSER.map_hash_values self, &block
     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.transform_keys}
     def transform_keys &block
       return hash.enum_for(:transform_keys) { size } unless block_given?
       NRSER.transform_keys self, &block
     end
     
     
+    # See {NRSER.symbolize_keys!}
     def symbolize_keys!
       NRSER.symbolize_keys! self
     end
     
     
+    # See {NRSER.symbolize_keys}
     def symbolize_keys
       NRSER.symbolize_keys self
     end
     
     
+    # See {NRSER.stringify_keys!}
+    def stringify_keys!
+      NRSER.stringify_keys! self
+    end
+    
+    
+    # See {NRSER.stringify_keys}
+    def stringify_keys
+      NRSER.stringify_keys self
+    end
+    
+    # See {NRSER.map_hash_keys}
     def map_keys &block
       NRSER.map_hash_keys self, &block
     end

data/lib/nrser/refinements/string.rb

@@ -19,5 +19,13 @@ module NRSER
     def truncate *args
       NRSER.truncate self, *args
     end
+    
+    # See {NRSER.constantize}
+    def constantize
+      NRSER.constantize self
+    end
+    
+    alias_method :to_const, :constantize
+    
   end # refine String
 end # NRSER

data/lib/nrser/string.rb

@@ -105,5 +105,55 @@ module NRSER
 
       "#{str[0, stop]}#{omission}"
     end
+    
+    # Get the constant identified by a string.
+    # 
+    # @example
+    #   
+    #   SomeClass == NRSER.constantize(SomeClass.name)
+    # 
+    # Lifted from ActiveSupport.
+    # 
+    # @param [String] camel_cased_word
+    #   The constant's camel-cased, double-colon-separated "name",
+    #   like "NRSER::Types::Array".
+    # 
+    # @return [Object]
+    # 
+    # @raise [NameError]
+    #   When the name is not in CamelCase or is not initialized.
+    # 
+    def constantize(camel_cased_word)
+      names = camel_cased_word.split('::')
+
+      # Trigger a built-in NameError exception including the ill-formed constant in the message.
+      Object.const_get(camel_cased_word) if names.empty?
+
+      # Remove the first blank element in case of '::ClassName' notation.
+      names.shift if names.size > 1 && names.first.empty?
+
+      names.inject(Object) do |constant, name|
+        if constant == Object
+          constant.const_get(name)
+        else
+          candidate = constant.const_get(name)
+          next candidate if constant.const_defined?(name, false)
+          next candidate unless Object.const_defined?(name)
+
+          # Go down the ancestors to check if it is owned directly. The check
+          # stops when we reach Object or the end of ancestors tree.
+          constant = constant.ancestors.inject do |const, ancestor|
+            break const    if ancestor == Object
+            break ancestor if ancestor.const_defined?(name, false)
+            const
+          end
+
+          # owner is in Object, so raise
+          constant.const_get(name, false)
+        end
+      end
+    end # constantize
+    
+    alias_method :to_const, :constantize
   end # class << self
 end # module NRSER

data/lib/nrser/types/hash.rb

@@ -21,7 +21,7 @@ module NRSER::Types
     def test value
       return false unless super(value)
       
-      if keys == NRSER::Types::ALL && values == NRSER::Types::ALL
+      if keys == NRSER::Types::ANY && values == NRSER::Types::ANY
         return true
       end
       

data/lib/nrser/version.rb

@@ -1,3 +1,3 @@
 module NRSER
-  VERSION = "0.0.19"
+  VERSION = "0.0.20"
 end

data/spec/nrser/meta/props_spec.rb

@@ -1,6 +1,6 @@
 require 'spec_helper'
 
-T = NRSER::Types
+using NRSER::Types
 
 describe NRSER::Meta::Props do
   
@@ -11,9 +11,9 @@ describe NRSER::Meta::Props do
     Class.new(NRSER::Meta::Props::Base) do
       # include NRSER::Meta::Props
       
-      prop :x, type: T.int
-      prop :y, type: T.int
-      prop :blah, type: T.str, source: :blah
+      prop :x, type: t.int
+      prop :y, type: t.int
+      prop :blah, type: t.str, source: :blah
       
       def blah
         "blah!"
@@ -38,7 +38,7 @@ describe NRSER::Meta::Props do
     expect(props[:blah].source?).to be true
     expect(props[:blah].primary?).to be false
     
-    primary_props = point.props primary: true
+    primary_props = point.props only_primary: true
     
     expect(primary_props.key? :blah).to be false
     
@@ -48,14 +48,14 @@ describe NRSER::Meta::Props do
     expect(p.y).to be 2
     
     expect(p.to_h).to eq({x: 1, y: 2, blah: "blah!"})
-    expect(p.to_h(primary: true)).to eq({x: 1, y: 2})
+    expect(p.to_h(only_primary: true)).to eq({x: 1, y: 2})
     
     expect { point.new x: 1, y: 'why?' }.to raise_error TypeError
     expect { p.x = 3 }.to raise_error NoMethodError
     
     p_hash = p.to_h
     
-    p2 = point.from_h p_hash
+    p2 = point.new p_hash
     
     expect(p2.x).to be 1
     expect(p2.y).to be 2

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nrser
 version: !ruby/object:Gem::Version
-  version: 0.0.19
+  version: 0.0.20
 platform: ruby
 authors:
 - nrser
@@ -101,6 +101,7 @@ files:
 - lib/nrser/meta/class_attrs.rb
 - lib/nrser/meta/props.rb
 - lib/nrser/meta/props/base.rb
+- lib/nrser/meta/props/prop.rb
 - lib/nrser/no_arg.rb
 - lib/nrser/refinements.rb
 - lib/nrser/refinements/array.rb