nrser 0.0.20 → 0.0.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 01fe1d56c4df90623c6407128463f67ca2e65426
-  data.tar.gz: 0b1dfcb6cdd036647526482901cffe7e652cf189
+  metadata.gz: e94f9b40217a5d9e632cf2baa64d5e5e0d39cf23
+  data.tar.gz: 5bd0fc14f35efd8c8c42873eddf35ec3261aa483
 SHA512:
-  metadata.gz: af6cf0974b665d43b2b56a5fecbc1c44c2014f2aeb031eb3b831d599d55003a5d83ba6a6cdf604b34fc64700a6f713a96c8d9b69e51f550a3008449ee2d5de79
-  data.tar.gz: e368146e2161490ed4a831063e6a79540e084c45c52a685801776b759c43cf37e5d679bad11bbe2b22fd8f2d78012276f73843a0afa0a14d54226bccd138b8ca
+  metadata.gz: 77102788f88d0de577d33e617b6b3fadf98c64c8fccec2415440d708f071518133147e9bea3bd6eedd02ee038fd3b23f578985edd80e2706a8611d30bb92b626
+  data.tar.gz: 98163e885104844aae596aa379f970780d271df8fdbeeae76f25a31460635c2de5bc1f8eec7008e67038ea84e7c35a5047676d3ee7d80504e7c6d82e1894c048

data/README.md

@@ -26,10 +26,7 @@ Or install it yourself as:
 
     $ gem install nrser
 
-## Contributing
 
-1. Fork it ( https://github.com/nrser/nrser-ruby/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+## Design
+
+

data/lib/nrser/collection.rb

@@ -1,4 +1,5 @@
 require 'set'
+require 'ostruct'
 
 module NRSER
   # include this module in any custom classes to have them treated as
@@ -10,9 +11,13 @@ module NRSER
       Array,
       Hash,
       Set,
+      OpenStruct,
     ]
   end
   
+  # Eigenclass (Singleton Class)
+  # ========================================================================
+  # 
   class << self
     
     # test if an object is considered a collection.
@@ -24,40 +29,73 @@ module NRSER
       Collection::STDLIB.any? {|cls| obj.is_a? cls} || obj.is_a?(Collection)
     end
     
-    # yield on each element of a collection or on the object itself if it's
+    
+    # Yield on each element of a collection or on the object itself if it's
     # not a collection. avoids having to normalize to an array to iterate over
     # something that may be an object OR a collection of objects.
     # 
-    # @param obj [Object] target object.
+    # **NOTE**  Implemented for our idea of a collection instead of testing
+    #           for response to `#each` (or similar) to avoid catching things
+    #           like {IO} instances, which include {Enumerable} but are 
+    #           probably not what is desired when using {NRSER.each}
+    #           (more likely that you mean "I expect one or more files" than
+    #           "I expect one or more strings which may be represented by
+    #           lines in an open {File}").
+    # 
+    # @param [Object] object
+    #   Target object.
     # 
-    # @yield each element of a collection or the target object itself.
+    # @yield
+    #   Each element of a collection or the target object itself.
     # 
-    # @return [Object] obj param.
+    # @return [Object]
+    #   `object` param.
     # 
-    def each obj, &block
-      if collection? obj
-        obj.each &block
+    def each object, &block
+      if collection? object
+        # We need to test for response because {OpenStruct} *will* respond to
+        # #each because *it will respond to anything* (which sucks), but it 
+        # will return `false` for `respond_to? :each` and the like, and this
+        # behavior could be shared by other collection objects, so it seems 
+        # like a decent idea.
+        if object.respond_to? :each_pair
+          object.each_pair &block
+        elsif object.respond_to? :each
+          object.each &block
+        else
+          raise TypeError.squished <<-END
+            Object #{ obj.inpsect } does not respond to #each or #each_pair
+          END
+        end
       else
-        block.call obj
-        obj
+        block.call object
       end
+      object
     end
     
-    # if `obj` is a collection, calls `#map` with the block. otherwise,
+    
+    # If `object` is a collection, calls `#map` with the block. Otherwise,
     # applies block to the object and returns the result.
     # 
-    # @param obj [Object] target object.
+    # See note in {NRSER.each} for discussion of why this tests for a
+    # collection instead of duck-typing `#map`.
+    # 
+    # @param [Object] object
+    #   Target object.
     # 
-    # @yield each element of a collection or the target object itself.
+    # @yield
+    #   Each element of a collection or the target object itself.
     # 
-    # @return [Object] the result of mapping or applying the block.
+    # @return [Object]
+    #   The result of mapping or applying the block.
     # 
-    def map obj, &block
-      if collection? obj
-        obj.map &block
+    def map object, &block
+      if collection? object
+        object.map &block
       else
-        block.call obj
+        block.call object
       end
-    end
-  end
-end
+    end # #map
+    
+  end # class << self
+end # module NRSER

data/lib/nrser/enumerable.rb

@@ -1,31 +1,161 @@
+require 'pp'
+
+require_relative './errors'
+
 module NRSER
-  # Maps an enumerable object to a *new* hash with the same keys and values 
-  # obtained by calling `block` with the current key and value.
+  
+  # Eigenclass (Singleton Class)
+  # ========================================================================
   # 
-  # If `enumerable` *does not* successfully respond to `#to_h` then it's 
-  # treated as a hash where it's elements are the keys and all the values
-  # are `nil`.
-  # 
-  # @return [Hash]
-  # 
-  def self.map_values enumerable, &block
-    # Short-cut for Hash itself - though it would of course work through the
-    # next step, it's going to probably be *the* most common argument type,
-    # and there's no reason to do the tests and set up the exception 
-    # handler if we already know what's up with it.
-    return NRSER.map_hash_values(enumerable, &block) if enumerable.is_a? Hash
-    
-    if enumerable.respond_to? :to_h
-      begin
-        hash = enumerable.to_h
-      rescue TypeError => e
+  class << self
+    # Maps an enumerable object to a *new* hash with the same keys and values 
+    # obtained by calling `block` with the current key and value.
+    # 
+    # If `enumerable` *does not* respond to `#to_pairs` then it's 
+    # treated as a hash where the elements iterated by `#each` are it's keys
+    # and all it's values are `nil`.
+    # 
+    # In this way, {NRSER.map_values} handles Hash, Array, Set, OpenStruct,
+    # and probably pretty much anything else reasonable you may throw at it.
+    # 
+    # @param [#each_pair, #each] enumerable
+    # 
+    # @yieldparam [Object] key
+    #   The key that will be used for whatever value the block returns in the
+    #   new hash.
+    # 
+    # @yieldparam [nil, Object] value
+    #   If `enumerable` responds to `#each_pair`, the second parameter it yielded
+    #   along with `key`. Otherwise `nil`.
+    # 
+    # @yieldreturn [Object]
+    #   Value for the new hash.
+    # 
+    # @return [Hash]
+    # 
+    # @raise [TypeError]
+    #   If `enumerable` does not respond to `#each_pair` or `#each`.
+    # 
+    def map_values enumerable, &block
+      result = {}
+      
+      if enumerable.respond_to? :each_pair
+        enumerable.each_pair { |key, value|
+          result[key] = block.call key, value
+        }
+      elsif enumerable.respond_to? :each
+        enumerable.each { |key| 
+          result[key] = block.call key, nil
+        }
+      else
+        raise TypeError.new NRSER.squish <<-END
+          First argument must respond to #each_pair or #each
+          (found #{ enumerable.inspect })
+        END
+      end
+      
+      result
+    end # #map_values
+    
+    
+    
+    # @todo Document find_bounded method.
+    # 
+    # @param [type] arg_name
+    #   @todo Add name param description.
+    # 
+    # @return [return_type]
+    #   @todo Document return value.
+    # 
+    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 }
+            
+            Found:
+              #{ NRSER.indent value.pretty_inspect }
+            
+            Enumerable:
+              #{ NRSER.indent enum.pretty_inspect }
+            
+          END
+        }
+    end # #find_bounded
+    
+    
+    
+    # @todo Document find_only method.
+    # 
+    # @param [type] arg_name
+    #   @todo Add name param description.
+    # 
+    # @return [return_type]
+    #   @todo Document return value.
+    # 
+    def find_only enum, &block
+      find_bounded(enum, 1, &block).first
+    end # #find_only
+    
+    
+    
+    # @todo Document to_h_by method.
+    # 
+    # @param [type] arg_name
+    #   @todo Add name param description.
+    # 
+    # @return [return_type]
+    #   @todo Document return value.
+    # 
+    def to_h_by enum, &block
+      {}.tap { |result|
+        enum.each { |element|
+          key = block.call element
+          
+          if result.key? key
+            raise NRSER::ConflictError.dedented <<-END
+              Key #{ key.inspect } is already in results with value:
+              
+              #{ result[key].pretty_inspect }
+            END
+          end
+          
+          result[key] = element
+        }
+      }
+    end # #to_h_by
+    
+    
+    # Create an {Enumerator} that iterates over the "values" of an 
+    # {Enumerable} `enum`. If `enum` responds to `#each_value` than we return
+    # that. Otherwise, we return `#each_entry`.
+    # 
+    # @param [Enumerable] enum
+    # 
+    # @return [Enumerator]
+    # 
+    # @raise [TypeError]
+    #   If `enum` doesn't respond to `#each_value` or `#each_entry`.
+    # 
+    def enumerate_as_values enum
+      # NRSER.match enum,
+      #   t.respond_to(:each_value), :each_value.to_proc,
+      #   t.respond_to(:each_entry), :each_entry.to_proc
+      # 
+      if enum.respond_to? :each_value
+        enum.each_value
+      elsif enum.respond_to? :each_entry
+        enum.each_entry
       else
-        return NRSER.map_hash_values hash, &block
+        raise TypeError.squished <<-END
+          Expected `enum` arg to respond to :each_value or :each_entry,
+          found #{ enum.inspect }
+        END
       end
-    end
+    end # #enumerate_as_values
+    
     
-    result = {}
-    enumerable.each { |key| result[key] = block.call key, nil }
-    result
-  end
+  end # class << self (Eigenclass)
 end # module NRSER

data/lib/nrser/errors.rb

@@ -0,0 +1,9 @@
+
+module NRSER
+
+  class Error < StandardError; end
+  
+  class ConflictError < Error; end
+
+end
+

data/lib/nrser/hash.rb

@@ -116,22 +116,6 @@ module NRSER
   
   
   
-  # @todo Document map_hash_values method.
-  # 
-  # @param [Hash] hash
-  #   @todo Add name param description.
-  # 
-  # @return [return_type]
-  #   @todo Document return value.
-  # 
-  def self.map_hash_values hash, &block
-    result = {}
-    hash.each { |key, value| result[key] = block.call key, value }
-    result
-  end # #map_hash_values
-  
-  
-  
   # Lifted from ActiveSupport
   # =====================================================================
   # 
@@ -228,7 +212,7 @@ module NRSER
   end
   
   # My-style name
-  singleton_class.send :alias_method, :map_hash_keys, :transform_keys
+  singleton_class.send :alias_method, :map_keys, :transform_keys
   
   
   # Mutates `hash` by converting all keys that respond to `#to_sym` to symbols.

data/lib/nrser/meta/class_attrs.rb

@@ -28,26 +28,66 @@ module ClassAttrs
   # Class methods to extend the receiver with when {NRSER::Meta::ClassAttrs}
   # is included.
   module ClassMethods
-    def instance_variable_lookup name
-      instance_variable_get(name) || if (
-        superclass.respond_to? :instance_variable_lookup
-      )
-        superclass.instance_variable_lookup name
+    def instance_variable_lookup  name,
+                                  default: NRSER::NO_ARG,
+                                  default_from: NRSER::NO_ARG
+      
+      # If it's defined here on self, return that
+      if instance_variable_defined? name
+        return instance_variable_get name
+      end
+      
+      # Ok, now to need to look for it.
+      
+      # See if the superclass has the lookup method
+      if superclass.respond_to? :instance_variable_lookup
+        # It does. See what we get from that. We create a new object to use
+        # as a flag and assign it to `default` so we can tell if the search
+        # failed.
+        not_found = Object.new
+        result = superclass.instance_variable_lookup name, default: not_found
+        
+        # If we found something, return it.
+        return result unless result == not_found
+        
+      end # if superclass.respond_to? :instance_variable_lookup
+      
+      # Ok, nothing was found.
+      
+      # See if we can use a default...
+      if default != NRSER::NO_ARG || default_from != NRSER::NO_ARG
+        # We can use a default.
+        # `default` takes precedence.
+        if default != NRSER::NO_ARG
+          default
+        else
+          send default_from
+        end
+        
       else
+        # Nope, we can't, raise.
         raise NoMethodError.new NRSER.squish <<-END
           #{ name.inspect } is not defined anywhere in the class hierarchy
         END
-      end
-    end
 
-    def class_attr_accessor attr
+      end # if we have a default value / else
+      
+    end # #instance_variable_lookup
+    
+
+    def class_attr_accessor attr,
+                            default: NRSER::NO_ARG,
+                            default_from: NRSER::NO_ARG
+      
       var_name = "@#{ attr }".to_sym
       
       singleton_class.class_eval do
         define_method(attr) do |*args|
           case args.length
           when 0
-            instance_variable_lookup var_name
+            instance_variable_lookup  var_name,
+                                      default: default,
+                                      default_from: default_from
           when 1
             instance_variable_set var_name, args[0]
           else
@@ -63,6 +103,16 @@ module ClassAttrs
         end
       end
     end
+    
+    def class_attr_writer attr
+      var_name = "@#{ attr }".to_sym
+      
+      singleton_class.class_eval do
+        define_method("#{ attr }=") do |value|
+          instance_variable_set var_name, value
+        end
+      end
+    end
   end # module ClassMethods
   
   # Extend the including class with {NRSER::Meta::ClassAttrs::ClassMethods}

data/lib/nrser/open_struct.rb

@@ -0,0 +1,60 @@
+module NRSER
+  
+  # Eigenclass (Singleton Class)
+  # ========================================================================
+  # 
+  class << self
+    
+    # Deeply convert a {Hash} to an {OpenStruct}.
+    # 
+    # @param [Hash] hash
+    # 
+    # @return [OpenStruct]
+    # 
+    # @raise [TypeError]
+    #   If `hash` is not a {Hash}.
+    # 
+    def to_open_struct hash, freeze: false
+      unless hash.is_a? Hash
+        raise TypeError,
+              "Argument must be hash (found #{ hash.inspect })"
+      end
+      
+      _to_open_struct hash, freeze: freeze
+    end # #to_open_struct
+    
+    
+    private
+    
+      def _to_open_struct value, freeze:
+        result = case value
+        when OpenStruct
+          # Just assume it's already taken care of if it's already an OpenStruct
+          value
+          
+        when Hash
+          OpenStruct.new(
+            map_values(value) { |k, v| _to_open_struct v, freeze: freeze }
+          )
+          
+        when Array
+          value.map { |v| _to_open_struct v, freeze: freeze }
+          
+        when Set
+          Set.new value.map { |v| _to_open_struct v, freeze: freeze }
+        
+        else
+          value
+        end
+        
+        if freeze
+          result.freeze
+        end
+        
+        result
+      end # ._to_open_struct
+    # end private
+    
+  end # class < self (Eigenclass)
+  
+end # module NRSER

data/lib/nrser/refinements/array.rb

@@ -1,8 +1,7 @@
+require_relative './enumerable'
+
 module NRSER
   refine ::Array do
-    # See {NRSER.map_array_values}
-    def map_values &block
-      NRSER.map_values self, &block
-    end
-  end # Array
+    include NRSER::Refinements::Enumerable
+  end # refine ::Array
 end # NRSER

data/lib/nrser/refinements/enumerable.rb

@@ -0,0 +1,41 @@
+module NRSER; end
+module NRSER::Refinements; end
+
+# Instance methods that are mixed in to the refinements of many classes that
+# include {Enumerable}, including {Array}, {Set}, {Hash} and {OpenStruct}.
+# 
+# All of these just proxy to a {NRSER} module (static) method, so the 
+# functionality can be used on older Rubies that can't refine.
+# 
+module NRSER::Refinements::Enumerable
+  
+  # See {NRSER.map_values}
+  def map_values &block
+    NRSER.map_values self, &block
+  end
+  
+  
+  # See {NRSER.find_bounded}
+  def find_bounded bounds, &block
+    NRSER.find_bounded self, bounds, &block
+  end
+  
+  
+  # See {NRSER.find_only}
+  def find_only &block
+    NRSER.find_only self, &block
+  end
+  
+  
+  # See {NRSER.to_h_by}
+  def to_h_by &block
+    NRSER.to_h_by self, &block
+  end
+  
+  # See {NRSER.enumerate_as_values}
+  def enumerate_as_values
+    NRSER.enumerate_as_values self
+  end
+  
+end # module NRSER::Refinements::Enumerable
+

data/lib/nrser/refinements/enumerator.rb

@@ -0,0 +1,7 @@
+require_relative './enumerable'
+
+module NRSER
+  refine ::Enumerator do
+    include NRSER::Refinements::Enumerable
+  end # refine ::Enumerator
+end # NRSER

data/lib/nrser/refinements/exception.rb

@@ -4,4 +4,32 @@ module NRSER
       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 message.squish
+    end
+    
+    # Create a new instance from the dedented message.
+    # 
+    # See {NRSER.dedent}.
+    # 
+    # @param [String] message
+    # 
+    # @return [Exception]
+    # 
+    def dedented message
+      new message.dedent
+    end
+    
+  end # refine Exception.singleton_class
 end # NRSER

data/lib/nrser/refinements/hash.rb

@@ -1,5 +1,10 @@
+require_relative './enumerable'
+
 module NRSER
+  
   refine ::Hash do
+    include NRSER::Refinements::Enumerable
+    
     # See {NRSER.except_keys!}.
     def except! *keys
       NRSER.except_keys! self, *keys
@@ -28,11 +33,6 @@ module NRSER
     end # #leaves
     
     
-    # See {NRSER.map_hash_values}.
-    def map_values &block
-      NRSER.map_hash_values self, &block
-    end
-    
     # See {NRSER.transform_keys!}
     def transform_keys! &block
       return enum_for(:transform_keys!) { size } unless block_given?
@@ -70,9 +70,11 @@ module NRSER
       NRSER.stringify_keys self
     end
     
+    
     # See {NRSER.map_hash_keys}
     def map_keys &block
-      NRSER.map_hash_keys self, &block
+      NRSER.map_keys self, &block
     end
-  end # Hash
+    
+  end # refine ::Hash
 end # NRSER

data/lib/nrser/refinements/open_struct.rb

@@ -0,0 +1,30 @@
+require 'ostruct'
+
+module NRSER 
+  refine OpenStruct do
+    
+    # Map values using {NRSER.map_values} into a new {OpenStruct} instance.
+    # 
+    # @return [OpenStruct]
+    # 
+    def map_values &block
+      self.class.new NRSER.map_values(self, &block)
+    end # #map_values
+    
+    
+    # See {NRSER.to_h_by}
+    def to_h_by &block
+      NRSER.to_h_by self, &block
+    end
+    
+  end
+  
+  refine OpenStruct.singleton_class do
+    
+    # See {NRSER.to_open_struct}.
+    def from_h hash, freeze: false
+      NRSER.to_open_struct hash, freeze: freeze
+    end # .from
+    
+  end
+end # module NRSER