xkeys 1.0.1 → 2.0.0

data/HISTORY.txt

@@ -1,4 +1,19 @@
+2014-03-21 Version 2.0.0
+
+	XKeys can now be used with data types other than array or hash
+	(as long as they support array- or hash-like interfaces).
+
+	New custom nodes can be generated by defining an #xkeys_new
+	method. The method is responsible for adding XKeys extensions to
+	the new node as needed/desired.
+
+	See Sarah::XK in gem sarah-xk for an example.
+
+	Using :[] (push mode) as the first of multiple keys now works
+	correctly.
+
 2013-07-25 Version 1.0.1
+
 	The auto-indexing array key for set has been changed from nil to
 	:[] in order to support nil keys (e.g. in case a NULL value from a
 	database field is being used as a nil key).
@@ -23,7 +38,9 @@
 	exception.
 
 2013-07-08 Version 0.0.2
+
 	Packaging and documentation cleanup.
 
 2013-07-08 Version 0.0.1
+
 	First release.

data/lib/xkeys.rb

@@ -1,5 +1,5 @@
 # XKeys - Extended keys to facilitate fetching and storing in nested
-#	hash and array structures with Perl-ish auto-vivification.
+#	hash- and array-like structures with Perl-ish auto-vivification.
 #
 # Synopsis:
 #  root = {}.extend XKeys::Hash
@@ -20,8 +20,13 @@
 #  root[1, 0, {}] # => 'value 1'
 #  root[1, 4, {}] # => nil
 #
+# As of version 2, other types with array- or hash-like behavior are
+# supported as well.
+#
+# Version 2.0.0 2014-03-21
+#
 # @author Brian Katzung <briank@kappacs.com>, Kappa Computer Solutions, LLC
-# @copyright 2013 Brian Katzung and Kappa Computer Solutions, LLC
+# @copyright 2013-2014 Brian Katzung and Kappa Computer Solutions, LLC
 # @license MIT License
 
 module XKeys; end
@@ -30,20 +35,21 @@ module XKeys; end
 module XKeys::Get
 
     # Perform an extended fetch using successive keys to traverse a tree
-    # of nested hashes and/or arrays.
+    # of nested hash- and/or array-like objects.
     #
     #   xfetch(key1, ..., keyN [, option_hash])
     #
-    #   Options:
+    # Options:
     #
     #   :else => default value
-    #       The default value to return if the specified keys do not exist.
+    #       The default value to return if any of the keys do not exist
+    #       (when an underlying #fetch generates a KeyError or IndexError).
     #       The :raise option takes precedence.
     #
     #   :raise => true
-    #       Raise a KeyError or IndexError if the specified keys do not
-    #       exist. This is the default behavior for xfetch in the absence
-    #       of an :else option.
+    #       Re-raise the original KeyError or IndexError if any of the keys
+    #       do not exist. This is the default behavior for xfetch in the
+    #       absence of an :else option.
     #
     #   :raise => *parameters
     #       Like :raise => true but does raise *parameters instead, e.g.
@@ -52,12 +58,13 @@ module XKeys::Get
 	if args[-1].is_a?(Hash) then options, last = args[-1], -2
 	else options, last = {}, -1
 	end
+
 	args[0..last].inject(self) do |node, key|
 	    begin node.fetch key
 	    rescue KeyError, IndexError
-		if options[:raise] and options[:raise] != true
+		if options[:raise] && options[:raise] != true
 		    raise *options[:raise]
-		elsif options[:raise] or !options.has_key? :else
+		elsif options[:raise] || !options.has_key?(:else)
 		    raise
 		else return options[:else]
 		end
@@ -68,21 +75,21 @@ module XKeys::Get
     # Perform an extended get using successive keys to traverse a tree of
     # nested hashes and/or arrays.
     #
-    #   [key] returns the hash or array element (or range-based array slice)
-    #   as normal.
+    # [key] or [range] returns the normal hash or array element (or
+    # range-based array slice).
     #
-    #   array[int1, int2] returns a length-based array slice as normal.
-    #   Append an option hash to force nested index behavior for two
-    #   integer array indexes: array[index1, index2, {}].
+    # [int1, int2] for arrays (or other objects responding to the #slice
+    # method) returns the object's normal two-parameter (e.g. start + length
+    # slice) index value.
     #
-    #   [key1, ..., keyN[, option_hash]] traverses a tree of nested
-    #   hashes and/or arrays using xfetch.
+    # [key1, ..., keyN[, option_hash]] traverses a tree of nested
+    # hash- and/or array-like objects using xfetch.
     #
-    #   Option :else => nil is used if no :else option is supplied.
-    #   See xfetch for option details.
+    # Option :else => nil is used if no :else option is supplied.
+    # See xfetch for option details.
     def [] (*args)
-	if args.count == 1 or (self.is_a?(Array) and args.count == 2 and
-	  args[0].is_a?(Integer) and args[1].is_a?(Integer))
+	if args.count == 1 || (respond_to?(:slice) && args.count == 2 &&
+	  args[0].is_a?(Integer) && args[1].is_a?(Integer))
 	    # [key] or array[start, length]
 	    super *args
 	else
@@ -101,45 +108,97 @@ end
 module XKeys::Set_
 
     # Common code for XKeys::Set_Hash and XKeys::Set_Auto. This method
-    # returns true if it is handling the set, or false if super should
-    # handle the set.
+    # returns true if it is handling the set, or false if the caller
+    # should super to handle the set.
+    #
+    #  _xkeys_set(key1, ..., keyN[, option_hash], value) { |key, options| block }
+    #
+    # If the root of the tree responds to the #xkeys_new method, it will
+    # be called as follows whenever a new node needs to be created:
     #
-    #  _xset(key1, ..., keyN[, options_hash], value) { |key, options| block }
+    #  xkeys_new(key2, info_hash, option_hash)
     #
-    #  The block should return true to auto-vivify an array or false to
-    #  auto-vivify a hash.
+    # where info_hash contains
     #
-    #  Options:
+    #  :node => The current node
+    #  :key1 => The key in the current node, or :[]
+    #  :block => The block passed to _xkeys_set
+    #
+    # The returned new node will be assigned to node[key1] (or pushed onto
+    # the end of the array) and should be appropriate to accept key2.
+    #
+    # Otherwise, the block should return true for array-like keys or false
+    # for hash-like keys. An array or hash node will be added accordingly.
+    #
+    # If a key is :[], the current node responds to the #push method, and
+    # push mode has not been disabled (see below), a new node will be
+    # pushed onto the end of the current node.
+    #
+    # Options:
     #
     #  :[] => false
-    #      Disable :[] auto-indexing
-    def _xset (*args)
+    #      Disable :[] push mode
+    def _xkeys_set (*args, &block)
 	if args[-2].is_a?(Hash) then options, last = args[-2], -3
 	else options, last = {}, -2
 	end
+
+	push_mode = options[:[]] != false
+
 	if args.count + last == 0
-	    if self.is_a?(Array) && args[0] == :[]
-		self << args[-1]	# array[:[]] = value
-	    else return false		# [key] = value ==> super
+	    if args[0] == :[] && push_mode && respond_to?(:push)
+		push args[-1]		# array[:[]] = value
+		true			# done--don't caller-super
+	    else false			# use caller-super to do it
 	    end
 	else
 	    # root[key1, ..., keyN[, option_hash]] = value
-	    (node, key) = args[1..last].inject([self, args[0]]) do |node, key|
-		if yield key, options
-		    node[0][node[1]] ||= []
-		    [node[0][node[1]], (key != :[]) ? key :
-		      node[0][node[1]].size]
+	    (node, key) = args[1..last].inject([self, args[0]]) do |nk1, k2|
+		if nk1[1] == :[] && push_mode && nk1[0].respond_to?(:push)
+		    # Push a new node onto an array-like node
+		    node = _xkeys_new(k2, { :node => nk1[0],
+		      :key1 => nk1[1], :block => block }, options)
+		    nk1[0].push node
+		    [node, k2]
+		elsif nk1[0][nk1[1]].nil?
+		    # Auto-vivify the specified key/index
+		    node = _xkeys_new(k2, { :node => nk1[0],
+		      :key1 => nk1[1], :block => block }, options)
+		    nk1[0][nk1[1]] = node
+		    [node, k2]
 		else
-		    node[0][node[1]] ||= {}
-		    [node[0][node[1]], key]
+		    # Traverse an existing node
+		    [nk1[0][nk1[1]], k2]
 		end
 	    end
-	    if yield key, options
-		node[(key != :[])? key : node.size] = args[-1]
-	    else node[key] = args[-1]
+
+	    # Assign (or push) according to the final key.
+	    if key == :[] && push_mode && node.respond_to?(:push)
+		node.push args[-1]
+	    else
+		node[key] = args[-1]
 	    end
+	    true	# done--don't caller-super
+	end
+    end
+
+    # Return a new node for node[key1] suitable to hold key2.
+    # Either key1 or key2 (or both) may be :[].
+    def _xkeys_new (key2, info, options)
+	if respond_to? :xkeys_new
+	    # Note: #xkeys_new is responsible for cloning extensions
+	    # as desired or needed.
+	    xkeys_new key2, info, options
+	else
+	    node = info[:block].call(key2, options) ? [] : {}
+
+	    # Clone XKeys extensions from the root node
+	    node.extend XKeys::Get if is_a? XKeys::Get
+	    node.extend XKeys::Set_Auto if is_a? XKeys::Set_Auto
+	    node.extend XKeys::Set_Hash if is_a? XKeys::Set_Hash
+
+	    node
 	end
-	true
     end
 
 end
@@ -152,10 +211,12 @@ module XKeys::Set_Hash
     # assignment syntax. :[] keys create nested arrays as needed. Other
     # keys, including integer keys, create nested hashes as needed.
     #
-    #   root[key1, ..., keyN[, options_hash]] = value
+    # See XKeys::Set_ for additional information.
+    #
+    #   root[key1, ..., keyN[, option_hash]] = value
     def []= (*args)
-	super args[0], args[-1] unless _xset(*args) do |key, opts|
-	  key == :[] and opts[:[]] != false
+	super args[0], args[-1] unless _xkeys_set(*args) do |key, options|
+	  key == :[] && options[:[]] != false
 	end
 	args[-1]
     end
@@ -171,10 +232,12 @@ module XKeys::Set_Auto
     # create nested arrays as needed. Other keys create nested hashes
     # as needed.
     #
-    #   root[key1, ..., keyN[, options_hash]] = value
+    # See XKeys::Set_ for additional information.
+    #
+    #   root[key1, ..., keyN[, option_hash]] = value
     def []= (*args)
-	super args[0], args[-1] unless _xset(*args) do |key, opts|
-	    (key == :[] and opts[:[]] != false) or key.is_a?(Integer)
+	super args[0], args[-1] unless _xkeys_set(*args) do |key, options|
+	    (key == :[] && options[:[]] != false) || key.is_a?(Integer)
 	end
 	args[-1]
     end

data/test/01get.rb

@@ -1,7 +1,7 @@
 require 'minitest/autorun'
 require 'xkeys'
 
-class TestXK < MiniTest::Unit::TestCase
+class TestXK_01 < MiniTest::Unit::TestCase
 
     def test_hash_get
 	h = { :a => 'a', :b => { :c => 'bc' },

data/test/02hash.rb

@@ -1,7 +1,7 @@
 require 'minitest/autorun'
 require 'xkeys'
 
-class TestXK < MiniTest::Unit::TestCase
+class TestXK_02 < MiniTest::Unit::TestCase
 
     def test_hash_set_hash
 	h = {}.extend XKeys::Set_Hash

data/test/03auto.rb

@@ -1,7 +1,7 @@
 require 'minitest/autorun'
 require 'xkeys'
 
-class TestXK < MiniTest::Unit::TestCase
+class TestXK_03 < MiniTest::Unit::TestCase
 
     def test_hash_set_auto
 	h = {}.extend XKeys::Set_Auto
@@ -34,6 +34,9 @@ class TestXK < MiniTest::Unit::TestCase
 
 	a[0, :[]] = '02'
 	assert_equal([ [ nil, '01', '02' ] ], a, "a[0, :[]] = '02'")
+
+	a.clear; a[0] = ?0; a[:[], 1] = ?1;
+	assert_equal([ ?0, [ nil, ?1 ] ], a, "a[:[], 1]")
     end
 
 end

data/test/04mod_combos.rb

@@ -1,7 +1,7 @@
 require 'minitest/autorun'
 require 'xkeys'
 
-class TestXK < MiniTest::Unit::TestCase
+class TestXK_04 < MiniTest::Unit::TestCase
 
     def test_hash
 	a = [].extend XKeys::Hash

data/test/05xkeys_new.rb

@@ -0,0 +1,18 @@
+require 'minitest/autorun'
+require 'xkeys'
+
+module MyNew
+
+    def xkeys_new (*args); "abcde"; end
+
+end
+
+class TestXK_05 < MiniTest::Unit::TestCase
+
+    def test_xkeys_new
+	a = [].extend(XKeys::Set_Auto).extend(MyNew)
+	a[0, 2] = 'X'
+	assert_equal([ "abXde" ], a, "a[0, 2] = 'X'")
+    end
+
+end

data/xkeys.gemspec

@@ -1,7 +1,7 @@
 Gem::Specification.new do |s|
   s.name         = "xkeys"
-  s.version      = "1.0.1"
-  s.date         = "2013-07-25"
+  s.version      = "2.0.0"
+  s.date         = "2014-03-21"
   s.authors      = ["Brian Katzung"]
   s.email        = ["briank@kappacs.com"]
   s.homepage     = "http://rubygems.org/gems/xkeys"

metadata

@@ -3,10 +3,10 @@ name: xkeys
 version: !ruby/object:Gem::Version 
   prerelease: false
   segments: 
-  - 1
+  - 2
   - 0
-  - 1
-  version: 1.0.1
+  - 0
+  version: 2.0.0
 platform: ruby
 authors: 
 - Brian Katzung
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2013-07-25 00:00:00 -05:00
+date: 2014-03-21 00:00:00 -05:00
 default_executable: 
 dependencies: []
 
@@ -34,6 +34,7 @@ files:
 - HISTORY.txt
 - test/03auto.rb
 - test/01get.rb
+- test/05xkeys_new.rb
 - test/04mod_combos.rb
 - test/02hash.rb
 has_rdoc: true
@@ -71,5 +72,6 @@ summary: Extended keys to facilitate fetching and storing in nested hash and arr
 test_files: 
 - test/03auto.rb
 - test/01get.rb
+- test/05xkeys_new.rb
 - test/04mod_combos.rb
 - test/02hash.rb