hash_pick 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 71c464d01eac460c7648f25a75ed9934f0edf762
-  data.tar.gz: 2b1f5e47a4625660f7558960d01bcf80eaa183ae
+  metadata.gz: 930eee6958a5e12f3706b0c47b2d8b36e8209a94
+  data.tar.gz: f3bbcca070e3d83dfba08d4286da1747bde8b6ed
 SHA512:
-  metadata.gz: ebe4a4af2e2f4b918883ec0ecd779b55bbfcf723895da8ca19b29edd982257ce476ff9c457bc0db6d0f5c4d44d002294937515009e6aef7bf50ca7ca1d976d1a
-  data.tar.gz: 8e78365148d86b93a711b624fb40b56a4567c24a8708b5d531414076a3a81192c2d3175fc222f1588b2d2d819481b733d7449f1518b48526548870b4ad06252b
+  metadata.gz: d9473e4453f82608a60450281e1c4fce27b3e78bed49bef720a30102a9d691a267c69802c3af1cce88eabc0413e3e9ef74721710dae133bb3634e3fe882ae642
+  data.tar.gz: 5d1e2ad8ef12b33f3ca3aba8d6e33e7fe4802f94e30731899880ba93047ee7da28498ba10f86502251ed303abfcb837941525b7b9e5e44b2d6cac3815f96008a

data/README.rdoc

@@ -7,7 +7,9 @@ Hash paths can be expressed as lists of keys of these types:
 * Object.
 * String.
 * Symbol.
-* Eithe String or Symbol.
+* Either String or Symbol.
+
+In addition, the general form of hash path query iteration is available in support of arbitrary path query semantics.
 
 The methods are provided by the module {HashPick}.
 

data/lib/hash_pick/version.rb

@@ -1,3 +1,3 @@
 module HashPick
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/hash_pick.rb

@@ -4,7 +4,7 @@
 # Fetch a value from a nested dictionary
 #
 # Provides methods for fetching a value from a nested dictionary (an object that implements +include?+ and +fetch+),
-# using a key path expressed as a list (+Enumerable+).
+# using a key path expressed as a list (an object that implements +inject+).
 #
 # The key path is iterated. In each iteration, the key is looked up in the dictionary, and the value found is used
 # as the dictionary for the next iteration. Lookup failure immediately returns nil.
@@ -45,22 +45,101 @@ module HashPick
   #   an ordered list of keys that implement +to_s+ and +to_sym+.
   # @return [Object] the value found at the path in the dictionary.
   # @return [nil] if any key lookup failed.
+  # @raise [ArgumentError] if +hash+ isn't a dictionary.
+  # @raise [ArgumentError] if +path+ isn't a list.
+  # @raise [ArgumentError] if any key in +path+ is +nil+.
   #
   def self.indifferent(hash, path)
-    path.inject(hash) do |acc, p|
-      break unless acc.respond_to?(:include?) && acc.respond_to?(:fetch)
+    assert_non_nil_path_keys(path)
+
+    pick(hash, path) do |acc, p|
       if acc.include?(p.to_sym)
         acc.fetch(p.to_sym)
       elsif acc.include?(p.to_s)
         acc[p.to_s]
       else
-        break
+        throw :break
+      end
+    end
+  end
+
+  ##
+  # General form of hash path iteration
+  #
+  # Passes to +block+, the dictionary and hash key for each iteration of the hash path, using
+  # the return value of the block as the dictionary for the next iteration, or as the return
+  # value of the last iteration. If the block throws +:break+, iteration is aborted.
+  #
+  # @example Complex hash path semantics
+  #
+  #   require "hash_pick"
+  #
+  #   dict = {
+  #     live: true,
+  #     sheldon: {
+  #       live: true,
+  #       first_name: "Sheldon",
+  #       last_name: "Hearn",
+  #     },
+  #     charles: {
+  #       first_name: "Charles",
+  #       last_name: "Mulder",
+  #     }
+  #   }
+  #
+  #   HashPick.pick(dict, [:sheldon, :first_name]) do |p, k|
+  #     throw :break unless p[:live] and p.include?(k)
+  #     p[k]
+  #   end
+  #   # => "Sheldon"
+  #
+  #   HashPick.pick(dict, [:charles, :first_name]) do |p, k|
+  #     throw :break unless p[:live] and p.include?(k)
+  #     p[k]
+  #   end
+  #   # => "Hearn"
+  #
+  # @param [Hash] hash
+  #   the dictionary to apply the +path+ to.
+  # @param [Array] path
+  #   an ordered list of path keys.
+  # @return [Object] the value of the last iteration.
+  # @return [nil] if +block+ throws +:break+ in any iteration.
+  # @raise [ArgumentError] if +hash+ isn't a dictionary.
+  # @raise [ArgumentError] if +path+ isn't a list.
+  #
+  def self.pick(hash, path, &block)
+    assert_dictionary(hash)
+    assert_enumerable_path(path)
+    catch(:break) do
+      path.inject(hash) do |acc, p|
+        break unless dictionary?(acc)
+        block.call(acc, p)
       end
     end
   end
 
   class << self
     alias_method :[], :indifferent
+
+    private
+
+    def assert_dictionary(hash)
+      raise ArgumentError.new("hash is not a dictionary") unless dictionary?(hash)
+    end
+
+    def dictionary?(hash)
+      hash.respond_to?(:include?) && hash.respond_to?(:fetch)
+    end
+
+    def assert_non_nil_path_keys(path)
+      raise ArgumentError.new("nil key in path") if path.any? { |p| p.nil? }
+    end
+
+    def assert_enumerable_path(path)
+      raise ArgumentError.new("path is not enumerable") unless path.respond_to?(:inject)
+    end
+
   end
 
   ##
@@ -74,12 +153,11 @@ module HashPick
   #   an ordered list of object keys.
   # @return [Object] the value found at the path in the dictionary.
   # @return [nil] if any key lookup failed.
+  # @raise [ArgumentError] if +hash+ isn't a dictionary.
+  # @raise [ArgumentError] if +path+ isn't a list.
   #
   def self.object(hash, path)
-    path.inject(hash) do |acc, p|
-      break unless acc.respond_to?(:include?) && acc.respond_to?(:fetch) && acc.include?(p)
-      acc[p]
-    end
+    pick(hash, path) { |acc, p| acc[p] }
   end
 
   ##
@@ -93,8 +171,12 @@ module HashPick
   #   an ordered list of keys that implement +to_sym+.
   # @return [Object] the value found at the path in the dictionary.
   # @return [nil] if any key lookup failed.
+  # @raise [ArgumentError] if +hash+ isn't a dictionary.
+  # @raise [ArgumentError] if +path+ isn't a list.
+  # @raise [ArgumentError] if any key in +path+ is +nil+.
   #
   def self.symbol(hash, path)
+    assert_non_nil_path_keys(path)
     object(hash, path.map(&:to_sym))
   end
 
@@ -109,8 +191,12 @@ module HashPick
   #   an ordered list of keys that implement +to_s+.
   # @return [Object] the value found at the path in the dictionary.
   # @return [nil] if any key lookup failed.
+  # @raise [ArgumentError] if +hash+ isn't a dictionary.
+  # @raise [ArgumentError] if +path+ isn't a list.
+  # @raise [ArgumentError] if any key in +path+ is +nil+.
   #
   def self.string(hash, path)
+    assert_non_nil_path_keys(path)
     object(hash, path.map(&:to_s))
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hash_pick
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Sheldon Hearn
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-02-13 00:00:00.000000000 Z
+date: 2017-02-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler