ruby-path 1.0.0

data/lib/path/core_ext.rb

@@ -0,0 +1,106 @@
+##
+# Data manipulation and retrieval methods for Array and Hash classes.
+
+module Path::DataExt
+
+  ##
+  # Checks if the given path exists and returns the first matching path
+  # as an array of keys. Returns false if no path is found.
+
+  def has_path? path
+    Path.find path, self do |d,k,p|
+      return true
+    end
+
+    false
+  end
+
+
+  ##
+  # Looks for data at paths matching path. Returns a hash of
+  # path array => data value pairs.
+  #
+  # If given a block will pass the parent data structure, the key
+  # or index of the item at given path, and the full path
+  # as an array of keys for each found path.
+  #
+  #   data = {:foo => "bar", :foobar => [:a, :b, {:foo => "other bar"}, :c]}
+  #   data.find_data "**/foo" do |parent, key, path|
+  #     p path
+  #     p parent[key]
+  #     puts "---"
+  #   end
+  #
+  #   # outputs:
+  #   # [:foo]
+  #   # "bar"
+  #   # ---
+  #   # [:foobar, 2, :foo]
+  #   # "other bar"
+  #   # ---
+  #
+  #   # returns:
+  #   # {[:foo] => "bar", [:foobar, 2, :foo] => "other bar"}
+
+  def find_data path, &block
+    Path.find path, self, &block
+  end
+
+
+  ##
+  # Finds and replaces the value of any match with the given new value.
+  # Returns true if matches were replaced, otherwise false.
+  #
+  #   data = {:foo => "bar", :foobar => [:a, :b, {:foo => "other bar"}, :c]}
+  #   data.replace_at_path "**=*bar", "BAR"
+  #   #=> true
+  #
+  #   data
+  #   #=> {:foo => "BAR", :foobar => [:a, :b, {:foo => "BAR"}, :c]}
+  #
+  # Note: Specifying a limit will allow only "limit" number of items to be
+  # set but may yield unpredictible results for non-ordered Hashes.
+  # It's also important to realize that arrays are modified starting with
+  # the last index, going down.
+
+  def replace_at_path path, value, limit=nil
+    count = 0
+
+    Path.find path, self do |data, key, path_arr|
+      count     = count.next
+      data[key] = value
+
+      return true if limit && count >= limit
+    end
+
+    return count > 0
+  end
+
+
+  ##
+  # Similar to DataExt#replace_at_path but deletes found items.
+  # Returns a hash of path/value pairs of deleted items.
+  #
+  #   data = {:foo => "bar", :foobar => [:a, :b, {:foo => "other bar"}, :c]}
+  #   data.replace_at_path "**=*bar", "BAR"
+  #   #=> {[:foo] => "bar", [:foobar, 2, :foo] => "other bar"}
+
+  def delete_at_path path, limit=nil
+    count = 0
+    out   = {}
+
+    Path.find path, self do |data, key, path_arr|
+      count         = count.next
+      out[path_arr] = data[key]
+
+      data.respond_to(:delete_at) ? data.delete_at(key) : data.delete(key)
+
+      return true if limit && count >= limit
+    end
+
+    return count > 0
+  end
+end
+
+Array.send :include, Path::DataExt
+Hash.send  :include, Path::DataExt

data/lib/path/match.rb

@@ -0,0 +1,130 @@
+##
+# Represents the single match of a relative path against a data set.
+
+class Path::Match < Array
+
+  attr_accessor :matches, :splat
+
+  def initialize *args
+    @matches = []
+    @splat   = []
+    super
+  end
+
+
+  def [] selector
+    path_match = super
+
+    if self.class === path_match
+      path_match.matches = @matches.dup
+      path_match.splat   = @splat.map{|key, sp| [key, sp.dup]}
+    end
+
+    path_match
+  end
+
+
+  def append_splat id, key # :nodoc:
+    if @splat[-1] && @splat[-1][0] == id
+      @splat[-1][1] << key
+    else
+      @splat << [id, [key]]
+    end
+  end
+
+
+  def dup # :nodoc:
+    path_match = super
+    path_match.matches = @matches.dup
+    path_match.splat   = @splat.map{|key, sp| [key, sp.dup]}
+    path_match
+  end
+
+
+  def append_match_for str, path # :nodoc:
+    match = @matches[str.to_i-1]
+    if match && !(String === match) && path[-1].empty?
+      path[-1] = match
+    else
+      path[-1] << match.to_s
+    end
+  end
+
+
+  ##
+  # Builds a path array by replacing %n and %% values with matches and splat.
+  #
+  #   matches = Path.find_in "**/foo=bar", data
+  #   # [["path", "to", "foo"]]
+  #
+  #   matches.first.make_path "root/%%/foo"
+  #   # ["root", "path", "to", "foo"]
+  #
+  #   matches = Path.find_in "path/*/(foo)=bar", data
+  #   # [["path", "to", "foo"]]
+  #
+  #   matches.first.make_path "root/%1/%2"
+  #   # ["root", "to", "foo"]
+
+  def make_path path_map, regex_opts=nil, &block
+    tmpsplat = @splat.dup
+    path     = []
+    escape   = false
+    replace  = false
+    new_item = true
+    rindex   = ""
+
+    path_map.to_s.chars do |chr|
+      case chr
+      when Path::ECH
+        escape = true
+
+      when Path::DCH
+        new_item = true
+
+      when Path::RCH
+        if replace
+          if rindex.empty?
+            unless tmpsplat.empty?
+              items = tmpsplat.shift[1].dup
+              if new_item
+                new_item = false
+              else
+                path[-1] = path[-1].dup << items.shift
+              end
+              path.concat items
+            end
+            replace = false
+          else
+            append_match_for(rindex, path)
+            rindex = ""
+          end
+
+          next
+        else
+          replace = true
+        end
+      end and next unless escape
+
+      if replace
+        if new_item && !rindex.empty? || chr.to_i.to_s != chr || escape
+          append_match_for(rindex, path) unless rindex.empty?
+          rindex  = ""
+          replace = false
+        else
+          rindex << chr
+        end
+      end
+
+      path      << ""  if new_item
+      path.last << chr unless replace
+
+      new_item = false
+      escape   = false
+    end
+
+    append_match_for(rindex, path) unless rindex.empty?
+
+    path
+  end
+end

data/lib/path/matcher.rb

@@ -0,0 +1,193 @@
+##
+# Path::Matcher is representation of a single node of a relative path used
+# to find values in a data set.
+
+class Path::Matcher
+
+  # Used as path item value to match any key or value.
+  module ANY_VALUE; end
+
+  # Shortcut characters that require modification before being turned into
+  # a matcher.
+  SUFF_CHARS = Regexp.escape "*?"
+
+  # All special path characters.
+  PATH_CHARS = Regexp.escape("()|") << SUFF_CHARS
+
+  # Path chars that get regexp escaped.
+  RESC_CHARS = "*?()|/"
+
+  # Matcher for Range path item.
+  RANGE_MATCHER  = %r{^(\-?\d+)(\.{2,3})(\-?\d+)$}
+
+  # Matcher for index,length path item.
+  ILEN_MATCHER   = %r{^(\-?\d+),(\-?\d+)$}
+
+  # Matcher allowing any value to be matched.
+  ANYVAL_MATCHER = /^(\?*\*+\?*)*$/
+
+  # Matcher to assert if any unescaped special chars are in a path item.
+  PATH_CHAR_MATCHER = /(^|[^#{Path::RECH}])([#{PATH_CHARS}])/
+
+
+  attr_reader :key, :value, :regex_opts
+  attr_accessor :recursive
+
+  ##
+  # New instance of Matcher. Options supported:
+  # :key:: String - The path item key to match.
+  # :value:: String - The path item value to match.
+  # :recursive:: Boolean - Look for path item recursively.
+  # :regex_opts:: Fixnum - representing the Regexp options.
+
+  def initialize opts={}
+    @regex_opts = opts[:regex_opts]
+    @recursive  = !!opts[:recursive]
+
+    @key = nil
+    @key = parse_node opts[:key] if
+      opts[:key] && !opts[:key].to_s.empty?
+
+    @value = nil
+    @value = parse_node opts[:value] if
+      opts[:value] && !opts[:value].to_s.empty?
+  end
+
+
+  def == other # :nodoc:
+    self.class  == other.class      &&
+    @key        == other.key        &&
+    @value      == other.value      &&
+    @regex_opts == other.regex_opts
+  end
+
+
+  ##
+  # Universal iterator for Hash and Array like objects.
+  # The data argument must either respond to both :each_with_index
+  # and :length, or respond to :has_key? and :each yielding a key/value pair.
+
+  def each_data_item data, &block
+    if data.respond_to?(:has_key?) && data.respond_to?(:each)
+      data.each(&block)
+
+    elsif data.respond_to?(:each_with_index) && data.respond_to?(:length)
+      # We need to iterate through the array this way
+      # in case items in it get deleted.
+      (data.length - 1).downto(0) do |i|
+        block.call i, data[i]
+      end
+    end
+  end
+
+
+  ##
+  # Finds data with the given key and value matcher, optionally recursive.
+  # Yields data, key and path Array when block is given.
+  # Returns an Array of path arrays.
+
+  def find_in data, path=nil, &block
+    return [] unless Array === data || Hash === data
+
+    paths  = []
+    path ||= Path::Match.new
+    path   = Path::Match.new path if path.class == Array
+
+    each_data_item data do |key, value|
+      c_path = path.dup << key
+
+      found, kmatch = match_node(@key, key)     if @key
+      found, vmatch = match_node(@value, value) if @value && (!@key || found)
+
+      c_path.append_splat self, key if @recursive
+
+      if found
+        c_path.matches.concat kmatch.to_a
+        c_path.matches.concat vmatch.to_a
+
+        f_path = c_path.dup
+        f_path.splat[-1][-1].pop if @key && !f_path.splat.empty?
+
+        yield data, key, f_path if block_given?
+        paths << f_path
+      end
+
+      paths.concat find_in(data[key], c_path, &block) if @recursive
+    end
+
+    paths
+  end
+
+
+  ##
+  # Check if data key or value is a match for nested data searches.
+  # Returns an array with a boolean expressing if the value matched the node,
+  # and the matches found.
+
+  def match_node node, value
+    return if ANY_VALUE != node &&
+              (Array === value || Hash === value)
+
+    if node.class == value.class
+      node == value
+
+    elsif Regexp === node
+      match = node.match value.to_s
+      return false unless match
+      match = match.size > 1 ? match[1..-1] : match.to_a
+      [true, match]
+
+    elsif Range === node
+      stat  = node.include? value.to_i
+      match = [value.to_i] if stat
+      [stat, match]
+
+    elsif ANY_VALUE == node
+      [true, [value]]
+
+    else
+      value.to_s == node.to_s
+    end
+  end
+
+
+  ##
+  # Decide whether to make path item matcher a regex, range, array, or string.
+
+  def parse_node str
+    case str
+    when nil, ANYVAL_MATCHER
+      ANY_VALUE
+
+    when RANGE_MATCHER
+      Range.new $1.to_i, $3.to_i, ($2 == "...")
+
+    when ILEN_MATCHER
+      Range.new $1.to_i, ($1.to_i + $2.to_i), true
+
+    when String
+      if @regex_opts || str =~ PATH_CHAR_MATCHER
+
+        # Remove extra suffix characters
+        str.gsub! %r{(^|[^#{Path::RECH}])(\*+\?*)}, '\1*'
+        str.gsub! %r{(^|[^#{Path::RECH}])\*+}, '\1*'
+
+        str = Regexp.escape str
+
+        # Remove escaping from special path characters
+        str.gsub! %r{#{Path::RECH}([#{PATH_CHARS}])}, '\1'
+        str.gsub! %r{#{Path::RECH}([#{RESC_CHARS}])}, '\1'
+        str.gsub! %r{(^|[^#{Path::RECH}])([#{SUFF_CHARS}])},   '\1(.\2)'
+        str.gsub! %r{(^|[^\.#{Path::RECH}])([#{SUFF_CHARS}])}, '\1(.\2)'
+
+        Regexp.new "\\A(?:#{str})\\Z", @regex_opts
+
+      else
+        str.gsub %r{#{Path::RECH}([^#{Path::RECH}]|$)}, '\1'
+      end
+
+    else
+      str
+    end
+  end
+end

data/lib/path/transaction.rb

@@ -0,0 +1,341 @@
+##
+# Path Transactions are a convenient way to apply selections and deletions
+# to complex data structures without having to know what state the data will
+# be in after each operation.
+#
+#   data = [
+#     {:name => "Jamie", :id => "12345"},
+#     {:name => "Adam",  :id => "54321"},
+#     {:name => "Kari",  :id => "12345"},
+#     {:name => "Grant", :id => "12345"},
+#     {:name => "Tory",  :id => "12345"},
+#   ]
+#
+#   # Select all element names, delete the one at index 2,
+#   # and move the element with the value "Tory" to the same path but
+#   # with the key renamed to "boo"
+#   Transaction.run data do |t|
+#     t.select "*/name"
+#     t.move "**=Tory" => "%%/boo"
+#     t.delete "2"
+#   end
+#
+#   # => [
+#   #  {:name => "Jamie"},
+#   #  {:name => "Adam"},
+#   #  {:name => "Grant"},
+#   #  {"boo" => "Tory"},
+#   # ]
+
+class Path::Transaction
+
+  ##
+  # Create new Transaction instance and run it with a block.
+  # Equivalent to:
+  #   Transaction.new(data).run(opts)
+
+  def self.run data, opts={}, &block
+    new(data).run opts, &block
+  end
+
+
+  attr_accessor :actions
+
+  ##
+  # Create a new Transaction instance with a the data object to perform
+  # operations on.
+
+  def initialize data
+    @data     = data
+    @new_data = nil
+    @actions  = []
+
+    @make_array = {}
+  end
+
+
+  ##
+  # Run operations as a transaction.
+  # See Transaction#results for supported options.
+
+  def run opts={}, &block
+    clear
+    yield self if block_given?
+    results opts
+  end
+
+
+  ##
+  # Returns the results of the transaction operations.
+  # To keep the original indicies of modified arrays, and return them as hashes,
+  # pass the :keep_indicies => true option.
+
+  def results opts={}
+    new_data = @data
+
+    @actions.each do |type, paths|
+      new_data = send("transaction_#{type}", new_data, *paths)
+    end
+
+    remake_arrays new_data, opts[:keep_indicies]
+  end
+
+
+  def remake_arrays new_data, except_modified=false # :nodoc:
+    remake_paths = @make_array.keys.sort{|p1, p2| p2.length <=> p1.length}
+
+    remake_paths.each do |path_arr|
+      key  = path_arr.last
+      obj = Path.data_at_path path_arr[0..-2], new_data
+
+      next unless obj && Hash === obj[key]
+
+      if except_modified
+        data_at_path = Path.data_at_path(path_arr, @data)
+        next if !data_at_path || obj[key].length != data_at_path.length
+      end
+
+      obj[key] = hash_to_ary obj[key]
+    end
+
+    new_data = hash_to_ary new_data if
+      (remake_paths.last == [] || Array === @data && Hash === new_data) &&
+      (!except_modified || @data.length == new_data.length)
+
+    new_data
+  end
+
+
+  def remap_make_arrays new_path, old_path # :nodoc:
+    @make_array[new_path] = true and return if @make_array[old_path]
+
+    @make_array.keys.each do |path|
+      if path[0...old_path.length] == old_path
+        path[0...old_path.length] = new_path
+      end
+    end
+  end
+
+
+  def transaction_select data, *data_paths # :nodoc:
+    return data if data_paths.empty?
+
+    transaction data, data_paths, true do |sdata, cdata, key, path, tpath|
+      sdata[key] = cdata[key]
+    end
+  end
+
+
+  def transaction_delete data, *data_paths # :nodoc:
+    transaction data, data_paths do |new_curr_data, curr_data, key|
+      new_curr_data.delete key
+    end
+  end
+
+
+  def transaction_move data, *path_pairs # :nodoc:
+    return data if path_pairs.empty?
+    path_val_hash = {}
+
+    new_data =
+      transaction data, path_pairs do |sdata, cdata, key, path, tpath|
+        path_val_hash[tpath] = sdata.delete key
+        remap_make_arrays(tpath, path)
+      end
+
+    force_assign_paths new_data, path_val_hash
+  end
+
+
+  def transaction_map data, *path_pairs # :nodoc:
+    return data if path_pairs.empty?
+    path_val_hash = {}
+
+    transaction data, path_pairs do |sdata, cdata, key, path, tpath|
+      tpath ||= path
+      path_val_hash[tpath] = sdata.delete key
+      remap_make_arrays(tpath, path)
+    end
+
+    force_assign_paths [], path_val_hash
+  end
+
+
+  def transaction data, data_paths, create_empty=false # :nodoc:
+    data_paths = data_paths.compact
+    return @new_data || data if data_paths.empty?
+
+    @new_data = create_empty ? Hash.new : data.dup
+
+    if Array === @new_data
+      @new_data = ary_to_hash @new_data
+    end
+
+    data_paths.each do |data_path|
+      # If data_path is an array, the second element is the path where the value
+      # should be mapped to.
+      data_path, target_path = data_path
+
+      Path.find data_path, data do |obj, k, path|
+        curr_data     = data
+        new_curr_data = @new_data
+
+        path.each_with_index do |key, i|
+          break unless new_curr_data
+
+          if i == path.length - 1
+            tpath = path.make_path target_path if target_path
+            yield new_curr_data, curr_data, key, path, tpath if block_given?
+
+          else
+            if create_empty
+              new_curr_data[key] ||= Hash.new
+
+            elsif new_curr_data[key] == curr_data[key]
+              new_curr_data[key] = Array === new_curr_data[key] ?
+                                    ary_to_hash(curr_data[key]) :
+                                    curr_data[key].dup
+            end
+
+            @make_array[path[0..i]] = true if Array === curr_data[key]
+
+            new_curr_data = new_curr_data[key]
+            curr_data     = curr_data[key]
+          end
+        end
+      end
+    end
+
+    @new_data
+  end
+
+
+  def force_assign_paths data, path_val_hash # :nodoc:
+    return data if path_val_hash.empty?
+    @new_data = (data.dup rescue [])
+
+    path_val_hash.each do |path, value|
+      curr_data     = data
+      new_curr_data = @new_data
+      prev_data     = nil
+      prev_key      = nil
+      prev_path     = []
+
+      path.each_with_index do |key, i|
+        if Array === new_curr_data
+          new_curr_data          = ary_to_hash new_curr_data
+          prev_data[prev_key]    = new_curr_data if prev_data
+          @new_data              = new_curr_data if i == 0
+          @make_array[prev_path] = true          if i == 0
+        end
+
+        last      = i == path.length - 1
+        prev_path = path[0..(i-1)] if i > 0
+        curr_path = path[0..i]
+        next_key  = path[i+1]
+
+        # new_curr_data is a hash from here on
+
+        @make_array.delete prev_path unless is_integer?(key)
+
+        new_curr_data[key] = value and break if last
+
+        if ary_or_hash?(curr_data) && child_ary_or_hash?(curr_data, key)
+          new_curr_data[key] ||= curr_data[key]
+
+        elsif !ary_or_hash?(new_curr_data[key])
+          new_curr_data[key] = is_integer?(next_key) ? [] : {}
+        end
+
+        @make_array[curr_path] = true if Array === new_curr_data[key]
+
+        prev_key      = key
+        prev_data     = new_curr_data
+        new_curr_data = new_curr_data[key]
+        curr_data     = curr_data[key] if ary_or_hash?(curr_data) rescue nil
+      end
+    end
+
+    @new_data
+  end
+
+
+  def is_integer? item # :nodoc:
+    item.to_s.to_i.to_s == item.to_s
+  end
+
+
+  def ary_or_hash? obj # :nodoc:
+    Array === obj || Hash === obj
+  end
+
+
+  def child_ary_or_hash? obj, key
+    ary_or_hash?(obj[key]) rescue false
+  end
+
+
+  def ary_to_hash ary # :nodoc:
+    hash = {}
+    ary.each_with_index{|val, i| hash[i] = val}
+    hash
+  end
+
+
+  def hash_to_ary hash # :nodoc:
+    hash.keys.sort.map{|k| hash[k] }
+  end
+
+
+  ##
+  # Clears the queued actions and cache.
+
+  def clear
+    @new_data = nil
+    @actions.clear
+    @make_array.clear
+  end
+
+
+  ##
+  # Queues path selects for transaction.
+
+  def select *paths
+    if @actions.last && @actions.last[0] == :select
+      @actions.last[1].concat paths
+    else
+      @actions << [:select, paths]
+    end
+  end
+
+
+  ##
+  # Queues path deletes for transaction.
+
+  def delete *paths
+    @actions << [:delete, paths]
+  end
+
+
+  ##
+  # Queues path moving for transaction. Moving a path will attempt to
+  # keep the original data structure and only affect the given paths.
+  # Empty hashes or arrays after a move are deleted.
+  #   t.move "my/path/1..4/key" => "new_path/%1/key",
+  #          "other/path/*"     => "moved/%1"
+
+  def move path_maps
+    @actions << [:move, Array(path_maps)]
+  end
+
+
+  ##
+  # Queues path mapping for transaction. Mapping a path will only keep the
+  # mapped values, completely replacing the original data structure.
+  #   t.map "my/path/1..4/key" => "new_path/%1/key",
+  #         "other/path/*"     => "moved/%1"
+
+  def map path_maps
+    @actions << [:map, Array(path_maps)]
+  end
+end