nrser 0.0.24 → 0.0.25

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ad84454dbdd85a4a86dbb940a0901cafe0effaef
-  data.tar.gz: 9992915527ce7f7749aac2d9bdf319a05507fd23
+  metadata.gz: 150628e4ec282944b3bfa4d667e0c678cfe9b6e3
+  data.tar.gz: d31edbf013cde3c160d3105e0ac0770efae26e88
 SHA512:
-  metadata.gz: 995db23a4d353e6a54fec4480e3d17175b99efb75a0a08cc0583a3b166fa1153a26ce58b66d2b592306a17d495ca3544a805a06a03fb06516337f072ee22eb91
-  data.tar.gz: 47488b4ca3a7655f5264578a6e9283b04e2e1148093c72ec032cbc03720f098d6e7531cd44ccc1e20f9ec3e4ea063a905fb4f4699b6793042a816e0a7f5d6ca7
+  metadata.gz: d170a8aeba6ed6940aa53a0d92a8f674e6b0b0bcaed15b8808b43dcde4ae690665fbd7f4bad2bc7ae72b641e675dd3e67228d935f0e0ba18e30605385bec54da
+  data.tar.gz: c71d68a17bb981b5638f9c28521d093fbf69266aa94323e96969c38301ad4293ba65ca1857cc6efaacc938f46a4857faff8ddfa737b6a200cac11dc8914e49a9

data/lib/nrser/enumerable.rb

@@ -59,21 +59,29 @@ module NRSER
     
     
     
-    # @todo Document find_bounded method.
+    # Find all entries in an {Enumerable} for which `&block` returns a truthy
+    # value, then check the amount of results found against the
+    # {NRSER::Types.length} created from `bounds`, raising a {TypeError} if 
+    # the results' length doesn't satisfy the bounds type.
     # 
-    # @param [type] arg_name
-    #   @todo Add name param description.
+    # @param [Enumerable] enum
+    #   The entries to search and check.
+    # 
+    # @param []
     # 
     # @return [return_type]
     #   @todo Document return value.
     # 
+    # @raise 
+    # 
     def find_bounded enum, bounds, &block
       NRSER::Types.
         length(bounds).
         check(enum.find_all &block) { |type:, value:|
           NRSER.dedent <<-END
             
-            Length of found elements (#{ value.length }) FAILED to satisfy #{ type.to_s }
+            Length of found elements (#{ value.length }) FAILED to 
+            satisfy #{ type.to_s }
             
             Found:
               #{ NRSER.indent value.pretty_inspect }
@@ -86,7 +94,6 @@ module NRSER
     end # #find_bounded
     
     
-    
     # @todo Document find_only method.
     # 
     # @param [type] arg_name
@@ -100,7 +107,6 @@ module NRSER
     end # #find_only
     
     
-    
     # @todo Document to_h_by method.
     # 
     # @param [type] arg_name

data/lib/nrser/hash.rb

@@ -291,4 +291,186 @@ module NRSER
     }
   end
   
+  
+  # Eigenclass (Singleton Class)
+  # ========================================================================
+  # 
+  class << self
+    
+    
+    
+    # @todo Document select_map method.
+    # 
+    # @param [type] arg_name
+    #   @todo Add name param description.
+    # 
+    # @return [return_type]
+    #   @todo Document return value.
+    # 
+    def select_map arg_name
+      # method body...
+    end # #select_map
+    
+    
+    # Guess which type of "name" key - strings or symbols - a hash (or other 
+    # object that responds to `#keys` and `#empty`) uses.
+    # 
+    # @param [#keys & #empty] keyed
+    #   Hash or similar object that responds to `#keys` and `#empty` to guess
+    #   about.
+    # 
+    # @return [nil]
+    #   If we can't determine the type of name keys used.
+    # 
+    # @return [Class]
+    #   If we can determine that {String} or {Symbol} keys are exclusively
+    #   used returns that class.
+    # 
+    def guess_name_type keyed
+      # We can't tell shit if the hash is empty
+      return nil if keyed.empty?
+      
+      name_types = keyed.
+        keys.
+        map( &:class ).
+        select { |klass| klass == String || klass == Symbol }.
+        uniq
+      
+      return name_types[0] if name_types.length == 1
+      
+      # There are both string and symbol keys present, we can't guess
+      nil
+    end # #guess_key_type
+    
+    
+    # @todo Document bury method.
+    # 
+    # @param [Hash] hash
+    #   Hash to bury the value in.
+    # 
+    # @param [Array | #to_s] key_path
+    #   -   When an {Array}, each entry is used exactly as-is for each key.
+    #       
+    #   -   Otherwise, the `key_path` is converted to a string and split by
+    #       `.` to produce the key array, and the actual keys used depend on 
+    #       the `parsed_key_type` option.
+    # 
+    # @param [Object] value
+    #   The value to set at the end of the path.
+    # 
+    # @param [Class | :guess] parsed_key_type:
+    #   How to handle parsed key path segments:
+    #   
+    #   -   `String` - use the strings that naturally split from a parsed
+    #       key path.
+    #       
+    #       Note that this is the *String class itself, **not** a value that 
+    #       is a String*.
+    #       
+    #   -   `Symbol` - convert the strings that are split from the key path
+    #       to symbols.
+    #       
+    #       Note that this is the *Symbol class itself, **not** a value that
+    #       is a Symbol*.``
+    #       
+    #   -   `:guess` (default) - 
+    # 
+    # @return [return_type]
+    #   @todo Document return value.
+    # 
+    def bury! hash,
+              key_path,
+              value,
+              parsed_key_type: :guess,
+              clobber: false
+      
+      # Parse the key if it's not an array
+      unless key_path.is_a?( Array )
+        key_path = key_path.to_s.split '.'
+        
+        # Convert the keys to symbols now if that's what we want to use
+        if parsed_key_type == Symbol
+          key_path.map! &:to_sym
+        end
+      end
+      
+      _internal_bury! \
+        hash,
+        key_path,
+        value,
+        guess_key_type: ( parsed_key_type == :guess ),
+        clobber: clobber
+    end # #bury
+    
+    
+    
+    private
+    # ========================================================================
+      
+      
+      # @todo Document _internal_bury! method.
+      # 
+      # @param [type] arg_name
+      #   @todo Add name param description.
+      # 
+      # @return [return_type]
+      #   @todo Document return value.
+      # 
+      def _internal_bury! hash,
+                          key_path,
+                          value,
+                          guess_key_type:,
+                          clobber:
+                          
+        # Split the key path into the current key and the rest of the keys
+        key, *rest = key_path
+        
+        # If we are guessing the key type and the hash uses some {Symbol}
+        # (and no {String}) keys then convert the key to a symbol.
+        if guess_key_type && guess_name_type( hash ) == Symbol
+          key = key.to_sym
+        end
+        
+        # Terminating case: we're at the last segment
+        if rest.empty?
+          # Set the value
+          hash[key] = value
+          
+        else
+          # Go deeper...
+          
+          # See if there is a hash in place
+          unless hash[key].is_a?( Hash )
+            # There is not... so we need to do some figurin'
+            
+            # If we're clobbering or the hash has no value, we're good:
+            # assign a new hash to set in
+            if clobber || ! hash.key?( key )
+              hash[key] = {}
+              
+            else
+              # We've got an intractable state conflict; raise
+              raise NRSER::ConflictError.new squish <<-END
+                can not set key #{ key.inspect } due to conflicting value
+                #{ hash[key].inspect } in hash #{ hash.inspect } (:clobber
+                option not set)
+              END
+              
+            end
+          end # unless hash[key].is_a?( Hash )
+          
+          # Dive in...
+          bury! hash[key], rest, value
+          
+        end # if rest.empty? / else
+      end # #_internal_bury!
+      
+      
+    # end private
+    
+    
+    
+  end # class << self (Eigenclass)
+  
+  
 end # module NRSER

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

@@ -1,3 +1,10 @@
+# Refinements
+# =======================================================================
+
+require 'nrser/refinements'
+using NRSER
+
+
 module NRSER
 module Meta 
 module Props 
@@ -8,6 +15,21 @@ class Base
   def initialize **values
     initialize_props values
   end
+  
+  # @todo Prob wanna improve this at some point, but it's better than nothing.
+  # 
+  # @return [String]
+  #   a short string describing the instance.
+  # 
+  def to_s
+    props_str = self.class.props( only_primary: true ).sort.map { |name, prop|
+      "#{ name }=#{ prop.get( self ).inspect }"
+    }.join ' '
+    
+    <<-END.squish
+      #<#{ self.class.name } #{ props_str }>
+    END
+  end # #to_s
 end # class Base
 
 end # module Props

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

@@ -1,8 +1,9 @@
 require 'nrser/no_arg'
 
 require 'nrser/refinements'
-require 'nrser/refinements/types'
+using NRSER
 
+require 'nrser/refinements/types'
 using NRSER::Types
 
 module NRSER 
@@ -20,13 +21,15 @@ class Prop
                   name,
                   type: t.any,
                   default: NRSER::NO_ARG,
-                  source: nil
+                  source: nil,
+                  to_data: nil
     
     @defined_in = defined_in
     @name = name
     @type = t.make type
     @source = source
     @default = default
+    @to_data = to_data
     
     if @source.nil?
       @instance_variable_source = false
@@ -113,7 +116,17 @@ class Prop
       if instance_variable_source?
         instance.instance_variable_get source
       else
-        instance.send source
+        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
       end
     else
       values(instance)[name]
@@ -166,26 +179,85 @@ class Prop
   end # #set_from_hash
   
   
-  
-  # @todo Document to_data method.
+  # Get the "data" value - a basic scalar or structure of hashes, arrays and
+  # scalars, suitable for JSON encoding, etc. - for the property from an
+  # instance.
   # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
+  # The process depends on the `to_data:` keyword provided at property
+  # declaration:
   # 
-  # @return [return_type]
-  #   @todo Document return value.
+  # 1.  {nil} *default*
+  #     -   If the property value responds to `#to_data`, the result of 
+  #         invoking that method will be returned.
+  #         
+  #         **WARNING**
+  #         
+  #         This can cause infinite recursion if an instance has
+  #         a property value that is also an instance of the same class (as
+  #         as other more complicated scenarios that boil down to the same 
+  #         problem), but, really, what else would it do in this situation?
+  #         
+  #         This problem can be avoided by by providing a `to_data:` keyword
+  #         when declaring the property that dictates how to handle it's value.
+  #         In fact, that was the motivation for adding `to_data:`.
+  #         
+  #     -   Otherwise, the value itself is returned, under the assumption that
+  #         it is already suitable as data.
+  #         
+  # 2.  {Symbol} | {String}
+  #     -   The `to_data:` string or symbol is sent to the property value
+  #         (the method with this name is called via {Object#send}).
+  #         
+  # 3.  {Proc}
+  #     -   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
+  #   Instance to get the property value form.
+  # 
+  # @return [Object]
+  #   Data representation of the property value (hopefully - the value itself
+  #   is returned if we don't have any better options, see above).
+  # 
+  # @raise [TypeError]
+  #   If {@to_data} (provided via the `to_data:` keyword at property 
+  #   declaration) is anything other than {nil}, {String}, {Symbol} or {Proc}.
   # 
   def to_data instance
     value = get instance
     
-    if value.respond_to? :to_data
-      value.to_data
+    case @to_data
+    when nil
+      if value.respond_to? :to_data
+        value.to_data
+      elsif type.respond_to? :to_data
+        type.to_data value
+      else
+        value
+      end
+    when Symbol, String
+      value.send @to_data
+    when Proc
+      @to_data.call value
     else
-      value
+      raise TypeError.squished <<-END
+        Expected `@to_data` to be Symbol, String or Proc;
+        found #{ @to_data.inspect }
+      END
     end
   end # #to_data
   
   
+  # @return [String]
+  #   a short string describing the instance.
+  # 
+  def to_s
+    <<-END.squish
+      #<#{ self.class.name }
+        #{ @defined_in.name }##{ @name }:#{ @type }>
+    END
+  end # #to_s  
+  
   
   private
     

data/lib/nrser/meta/props.rb

@@ -87,13 +87,16 @@ module Props
   # 
   module ClassMethods
     
-    # @todo Document props method.
+    # Get a map of property names to property instances.
     # 
-    # @param [type] arg_name
-    #   @todo Add name param description.
+    # @param [Boolean] only_own:
+    #   Don't include super-class properties.
     # 
-    # @return [return_type]
-    #   @todo Document return value.
+    # @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)
@@ -118,13 +121,17 @@ module Props
     end # #own_props
     
     
-    # @todo Document prop method.
+    # Define a property.
+    # 
+    # @param [Symbol] name
+    #   The name of the property.
     # 
-    # @param [type] arg_name
-    #   @todo Add name param description.
+    # @param [Hash{ Symbol => Object }] **opts
+    #   Constructor options for {NRSER::Meta::Props::Prop}.
     # 
-    # @return [return_type]
-    #   @todo Document return value.
+    # @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
@@ -153,6 +160,8 @@ module Props
           #   end
         end
       end
+      
+      prop
     end # #prop
     
     
@@ -212,6 +221,7 @@ module Props
       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 -
@@ -241,19 +251,30 @@ module Props
   end # #to_data
   
   
-  # @todo Document to_json method.
+  
+  # Language Inter-Op
+  # ---------------------------------------------------------------------
+  
+  # Get a JSON {String} encoding the instance's data.
   # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
+  # @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 [return_type]
-  #   @todo Document return value.
+  # @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

data/lib/nrser/refinements/hash.rb

@@ -76,5 +76,18 @@ module NRSER
       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
+    
   end # refine ::Hash
 end # NRSER

data/lib/nrser/refinements/pathname.rb

@@ -33,5 +33,16 @@ module NRSER
         super pattern, replacement
       end
     end
+    
+    
+    # Just returns `self`. Implemented to match the {String#to_pn} API so it
+    # can be called on an argument that may be either one.
+    # 
+    # @return [Pathname]
+    # 
+    def to_pn
+      Pathname.new self
+    end
+    
   end # Pathname
 end # NRSER

data/lib/nrser/refinements.rb

@@ -1,3 +1,5 @@
+require 'nrser'
+
 require_relative './refinements/object'
 require_relative './refinements/string'
 require_relative './refinements/array'

data/lib/nrser/spex.rb

@@ -0,0 +1,68 @@
+##############################################################################
+# RSpec helpers, shared examples, and other goodies.
+# 
+# This file is *not* required by default when `nrser` is since it **defines
+# global methods** and is not needed unless you're in [Rspec][].
+# 
+# [Rspec]: http://rspec.info/
+# 
+##############################################################################
+
+
+# Helpers
+# =====================================================================
+
+# Merge "expectation" hashes by appending all clauses for each state.
+# 
+# @example
+#   
+# 
+# @param [Array<Hash>] *expectations
+#   Splat of "expectation" hashes - see the examples.
+# 
+def merge_expectations *expectations
+  Hash.new { |result, state|
+    result[state] = []
+  }.tap { |result| 
+    expectations.each { |ex|
+      ex.each { |state, clauses|
+        result[state] += clauses.to_a
+      }
+    }
+  }
+end
+
+
+# Refine the subject of the parent scope by `#send`ing it a message and setting
+# the result as the new subject.
+# 
+# @param [Symbol | String] method_name
+#   Name of the method to send to.
+# 
+# @param [Array] args*
+#   Arguments to send to the method.
+# 
+# @return [void]
+#   Seems to be what RSpec's `subject` method returns.
+# 
+def refine_subject method_name, *args
+  subject {
+    super().send method_name, *args
+  }
+end # #refine_subject
+
+
+# Shared Examples
+# =====================================================================
+
+shared_examples "expect subject" do |*expectations|
+  merge_expectations( *expectations ).each { |state, specs|
+    specs.each { |verb, noun|
+      it {
+        # like: is_expected.to(include(noun))
+        is_expected.send state, self.send(verb, noun)
+      }
+    }
+  }
+end # is expected
+