nuggets 0.9.9 → 1.0.0

data/lib/nuggets/hash/deep_fetch.rb

@@ -0,0 +1,5 @@
+require 'nuggets/hash/deep_fetch_mixin'
+
+class Hash
+  include Nuggets::Hash::DeepFetchMixin
+end

data/lib/nuggets/hash/deep_fetch_mixin.rb

@@ -0,0 +1,74 @@
+#--
+###############################################################################
+#                                                                             #
+# nuggets -- Extending Ruby                                                   #
+#                                                                             #
+# Copyright (C) 2007-2014 Jens Wille                                          #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@gmail.com>                                       #
+#                                                                             #
+# nuggets is free software; you can redistribute it and/or modify it under    #
+# the terms of the GNU Affero General Public License as published by the Free #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# nuggets is distributed in the hope that it will be useful, but WITHOUT ANY  #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for     #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU Affero General Public License    #
+# along with nuggets. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                             #
+###############################################################################
+#++
+
+module Nuggets
+  class Hash
+    module DeepFetchMixin
+
+  # call-seq:
+  #   hash.deep_fetch(path[, separator]) => anObject
+  #   hash.deep_fetch(path[, separator]) { |key| ... } => anObject
+  #
+  # Recursively fetches keys in +path+, separated by +separator+
+  # if +path+ is not an array, from _hash_. Maps each individual
+  # key according to the block if provided.
+  #
+  # Examples:
+  #
+  #   hash = { 'foo' => { 'bar' => { 'baz' => 42 }, 'bay' => 23 } }
+  #   hash.deep_fetch('foo/bar/baz') #=> 42
+  #   hash.deep_fetch('foo/bar/bax') #=> nil
+  #   hash.deep_fetch('foo/bax/baz') #=> KeyError
+  #   hash.deep_fetch('foo/bay/baz') #=> TypeError
+  #   hash % 'foo/bar/baz' #=> 42
+  #   hash % %w[foo bar baz] #=> 42
+  #
+  #   hash = { foo: { bar: { baz: 42 } } }
+  #   hash.deep_fetch('foo/bar/baz', &:to_sym) #=> 42
+  #   hash % [:foo, :bar, :baz] #=> 42
+  def deep_fetch(path, separator = '/')
+    keys = path.is_a?(::Array) ? path : path.split(separator)
+    raise ::ArgumentError, 'no keys given' if keys.empty?
+
+    hash, klass = self, self.class
+
+    loop {
+      key = keys.shift
+      key = yield key if block_given?
+
+      return hash[key] if keys.empty?
+
+      unless (hash = hash.fetch(key)).is_a?(klass)
+        raise ::TypeError, '%p: %s expected, got %s' % [key, klass, hash.class]
+      end
+    }
+  end
+
+  alias_method :%, :deep_fetch
+
+    end
+  end
+end

data/lib/nuggets/hash/deep_merge.rb

@@ -0,0 +1,5 @@
+require 'nuggets/hash/deep_merge_mixin'
+
+class Hash
+  include Nuggets::Hash::DeepMergeMixin
+end

data/lib/nuggets/hash/deep_merge_mixin.rb

@@ -0,0 +1,53 @@
+#--
+###############################################################################
+#                                                                             #
+# nuggets -- Extending Ruby                                                   #
+#                                                                             #
+# Copyright (C) 2007-2011 Jens Wille                                          #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@gmail.com>                                       #
+#                                                                             #
+# nuggets is free software; you can redistribute it and/or modify it under    #
+# the terms of the GNU Affero General Public License as published by the Free #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# nuggets is distributed in the hope that it will be useful, but WITHOUT ANY  #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for     #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU Affero General Public License    #
+# along with nuggets. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                             #
+###############################################################################
+#++
+
+module Nuggets
+  class Hash
+    module DeepMergeMixin
+
+  # call-seq:
+  #   hash.deep_merge(other_hash) => aHash
+  #
+  # Merges nested hashes recursively (see Hash#merge).
+  def deep_merge(other)
+    merge(other) { |key, old, new|
+      old.respond_to?(:deep_merge) ? old.deep_merge(new) : new
+    }
+  end
+
+  # call-seq:
+  #   hash.deep_merge!(other_hash) => hash
+  #
+  # Destructive version of #deep_merge.
+  def deep_merge!(other)
+    replace(deep_merge(other))
+  end
+
+  alias_method :deep_update, :deep_merge!
+
+    end
+  end
+end

data/lib/nuggets/hash/idmap.rb

@@ -0,0 +1,5 @@
+require 'nuggets/hash/idmap_mixin'
+
+class Hash
+  extend Nuggets::Hash::IDMapMixin
+end

data/lib/nuggets/hash/idmap_mixin.rb

@@ -0,0 +1,41 @@
+#--
+###############################################################################
+#                                                                             #
+# nuggets -- Extending Ruby                                                   #
+#                                                                             #
+# Copyright (C) 2007-2013 Jens Wille                                          #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@gmail.com>                                       #
+#                                                                             #
+# nuggets is free software; you can redistribute it and/or modify it under    #
+# the terms of the GNU Affero General Public License as published by the Free #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# nuggets is distributed in the hope that it will be useful, but WITHOUT ANY  #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for     #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU Affero General Public License    #
+# along with nuggets. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                             #
+###############################################################################
+#++
+
+module Nuggets
+  class Hash
+    module IDMapMixin
+
+  def idmap(counter = 0)
+    if block_given?
+      new { |hash, key| hash[key] = yield(counter += 1) }
+    else
+      new { |hash, key| hash[key] = counter += 1 }
+    end
+  end
+
+    end
+  end
+end

data/lib/nuggets/hash/in_order.rb

@@ -0,0 +1,43 @@
+#--
+###############################################################################
+#                                                                             #
+# nuggets -- Extending Ruby                                                   #
+#                                                                             #
+# Copyright (C) 2007-2011 Jens Wille                                          #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@gmail.com>                                       #
+#                                                                             #
+# nuggets is free software; you can redistribute it and/or modify it under    #
+# the terms of the GNU Affero General Public License as published by the Free #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# nuggets is distributed in the hope that it will be useful, but WITHOUT ANY  #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for     #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU Affero General Public License    #
+# along with nuggets. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                             #
+###############################################################################
+#++
+
+require 'nuggets/array/in_order'
+
+class Hash
+
+  # call-seq:
+  #   hash.in_order(*ordered) => anArray
+  #
+  # Returns <tt>hash#to_a</tt>, in forced order (cf. Array#in_order).
+  #
+  # Examples:
+  #   { :a => 1, :b => 2, :c => 3 }.in_order(:b, :c)  #=> [[:b, 2], [:c, 3], [:a, 1]]
+  #   { :a => 1, :b => 2, :c => 3 }.in_order(:b, :d)  #=> [[:b, 2], [:a, 1], [:c, 3]]
+  def in_order(*ordered)
+    keys.in_order(*ordered).map { |key| [key, self[key]] }
+  end
+
+end

data/lib/nuggets/hash/insert.rb

@@ -0,0 +1,53 @@
+#--
+###############################################################################
+#                                                                             #
+# nuggets -- Extending Ruby                                                   #
+#                                                                             #
+# Copyright (C) 2007-2011 Jens Wille                                          #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@gmail.com>                                       #
+#                                                                             #
+# nuggets is free software; you can redistribute it and/or modify it under    #
+# the terms of the GNU Affero General Public License as published by the Free #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# nuggets is distributed in the hope that it will be useful, but WITHOUT ANY  #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for     #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU Affero General Public License    #
+# along with nuggets. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                             #
+###############################################################################
+#++
+
+class Hash
+
+  # call-seq:
+  #   hash.insert(other) => new_hash
+  #   hash.insert(other) { |key, old_value, new_value| ... } => new_hash
+  #
+  # Inserts +other+ into _hash_, while merging existing values instead of just
+  # overwriting. Uses default Hash#merge or block for merging.
+  def insert(other, &block)
+    block ||= lambda { |key, old_val, new_val|
+      old_val.is_a?(::Hash) && new_val.is_a?(::Hash) ?
+        old_val.merge(new_val, &block) : new_val
+    }
+
+    merge(other, &block)
+  end
+
+  # call-seq:
+  #   hash.insert!(other) => hash
+  #   hash.insert!(other) { |key, old_value, new_value| ... } => hash
+  #
+  # Destructive version of #insert.
+  def insert!(other, &block)
+    replace(insert(other, &block))
+  end
+
+end

data/lib/nuggets/hash/nest.rb

@@ -0,0 +1,5 @@
+require 'nuggets/hash/nest_mixin'
+
+class Hash
+  extend Nuggets::Hash::NestMixin
+end

data/lib/nuggets/hash/nest_mixin.rb

@@ -0,0 +1,78 @@
+#--
+###############################################################################
+#                                                                             #
+# nuggets -- Extending Ruby                                                   #
+#                                                                             #
+# Copyright (C) 2007-2011 Jens Wille                                          #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@gmail.com>                                       #
+#                                                                             #
+# nuggets is free software; you can redistribute it and/or modify it under    #
+# the terms of the GNU Affero General Public License as published by the Free #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# nuggets is distributed in the hope that it will be useful, but WITHOUT ANY  #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for     #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU Affero General Public License    #
+# along with nuggets. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                             #
+###############################################################################
+#++
+
+module Nuggets
+  class Hash
+    module NestMixin
+
+  # call-seq:
+  #   Hash.nest([depth]) => aHash
+  #   Hash.nest([depth[, value]]) => aHash
+  #   Hash.nest([depth]) { |key| ... } => aHash
+  #
+  # Creates a nested hash, +depth+ levels deep. The final hash will receive a
+  # default value of +value+ or, if +value+ is not given but a block is given,
+  # the result of the key yielded to that block, or, otherwise, the hash's
+  # original default value, typically +nil+.
+  #
+  # NOTE: If you set the default value for one of the nested hashes explicitly,
+  # all of the effects described here disappear for that hash because that also
+  # means that the default proc will be cleared.
+  #
+  # Example:
+  #
+  #   hash = Hash.nest(3)
+  #   hash[:foo][:bar][:a] = { :x => 1, :y => 2 }
+  #   hash[:foo][:bar][:b] = { :x => 0, :y => 3 }
+  #   hash
+  #   #=> {:foo=>{:bar=>{:b=>{:y=>3, :x=>0}, :a=>{:y=>2, :x=>1}}}}
+  def nest(depth = 0, value = default = true)
+    if depth.zero?
+      if default
+        if block_given?
+          new { |hash, key| hash[key] = yield(key) }
+        else
+          new { |hash, key| hash[key] = hash.default }
+        end
+      else
+        new { |hash, key| hash[key] = value }
+      end
+    else
+      if default
+        if block_given?
+          new { |hash, key| hash[key] = nest(depth - 1, &::Proc.new) }
+        else
+          new { |hash, key| hash[key] = nest(depth - 1) }
+        end
+      else
+        new { |hash, key| hash[key] = nest(depth - 1, value) }
+      end
+    end
+  end
+
+    end
+  end
+end

data/lib/nuggets/hash/only.rb

@@ -0,0 +1,52 @@
+#--
+###############################################################################
+#                                                                             #
+# nuggets -- Extending Ruby                                                   #
+#                                                                             #
+# Copyright (C) 2007-2011 Jens Wille                                          #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@gmail.com>                                       #
+#                                                                             #
+# nuggets is free software; you can redistribute it and/or modify it under    #
+# the terms of the GNU Affero General Public License as published by the Free #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# nuggets is distributed in the hope that it will be useful, but WITHOUT ANY  #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for     #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU Affero General Public License    #
+# along with nuggets. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                             #
+###############################################################################
+#++
+
+require 'nuggets/hash/at'
+
+class Hash
+
+  # call-seq:
+  #   hash.only => aHash
+  #   hash.only(+true+) => aHash
+  #
+  # Returns the only key/value pair of _hash_. Raises an IndexError if _hash_'s
+  # size is not 1, unless parameter +true+ is passed.
+  def only(relax = size == 1, split = false)
+    relax ? split ? Array(*first) : first :
+      raise(::IndexError, 'not a single-element hash')
+  end
+
+  # call-seq:
+  #   hash.only_pair => anArray
+  #   hash.only_pair(+true+) => anArray
+  #
+  # Returns the only key/value pair of _hash_ as an array. Raises an IndexError
+  # if _hash_'s size is not 1, unless parameter +true+ is passed.
+  def only_pair(relax = size == 1)
+    only(relax, true)
+  end
+
+end

data/lib/nuggets/hash/seen.rb

@@ -0,0 +1,5 @@
+require 'nuggets/hash/seen_mixin'
+
+class Hash
+  extend Nuggets::Hash::SeenMixin
+end

data/lib/nuggets/hash/seen_mixin.rb

@@ -0,0 +1,58 @@
+#--
+###############################################################################
+#                                                                             #
+# nuggets -- Extending Ruby                                                   #
+#                                                                             #
+# Copyright (C) 2007-2012 Jens Wille                                          #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@gmail.com>                                       #
+#                                                                             #
+# nuggets is free software; you can redistribute it and/or modify it under    #
+# the terms of the GNU Affero General Public License as published by the Free #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# nuggets is distributed in the hope that it will be useful, but WITHOUT ANY  #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for     #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU Affero General Public License    #
+# along with nuggets. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                             #
+###############################################################################
+#++
+
+module Nuggets
+  class Hash
+    module SeenMixin
+
+  # call-seq:
+  #   Hash.seen([seen[, unseen]]) => aHash
+  #
+  # Returns a hash that returns +unseen+ as the default value for a key that
+  # wasn't seen before and +seen+ for a key that was.
+  #
+  # Examples:
+  #
+  #   hash = Hash.seen
+  #   hash[:foo]  #=> false
+  #   hash[:foo]  #=> true
+  #   hash[:foo]  #=> true
+  #   hash[:bar]  #=> false
+  #   hash[:bar]  #=> true
+  #
+  #   hash = Hash.seen(42, 23)
+  #   hash[:foo]  #=> 23
+  #   hash[:foo]  #=> 42
+  #   hash[:foo]  #=> 42
+  #   hash[:bar]  #=> 23
+  #   hash[:bar]  #=> 42
+  def seen(seen = true, unseen = false)
+    new { |hash, key| hash[key] = seen; unseen }
+  end
+
+    end
+  end
+end