kronk 1.3.1 → 1.4.0

data/lib/kronk/data_set.rb

@@ -1,6 +1,8 @@
 class Kronk
 
   ##
+  # THIS CLASS IS DEPRECATED AND WILL BE REMOVED IN KRONK-1.5.x
+  #
   # Wraps a complex data structure to provide a search-driven interface.
 
   class DataSet
@@ -23,17 +25,20 @@ class Kronk
     # Modify the data object by passing inclusive or exclusive data paths.
     # Supports the following options:
     # :only_data:: String/Array - keep data that matches the paths
-    # :only_data_with:: String/Array - keep data with a matched child
     # :ignore_data:: String/Array - remove data that matches the paths
+    #
+    # Deprecated options:
+    # :only_data_with:: String/Array - keep data with a matched child
     # :ignore_data_with:: String/Array - remove data with a matched child
     #
     # Note: the data is processed in the following order:
-    # * only_data_with
-    # * ignore_data_with
     # * only_data
     # * ignore_data
 
     def modify options
+      warn_path_deprecation! if options[:ignore_data_with] ||
+                                options[:only_data_with]
+
       collect_data_points options[:only_data_with], true if
         options[:only_data_with]
 
@@ -48,31 +53,51 @@ class Kronk
     end
 
 
+    ##
+    # New implementation of DataSet#modify
+
+    def fetch options
+      warn_path_deprecation! if options[:ignore_data_with] ||
+                                options[:only_data_with]
+
+      options[:only_data]   = [*options[:only_data]].compact
+      options[:ignore_data] = [*options[:ignore_data]].compact
+
+      options[:only_data].concat(
+        [*options[:only_data_with]].map!{|path| path << "/.."}
+      ) if options[:only_data_with]
+
+      options[:ignore_data].concat(
+        [*options[:ignore_data_with]].map!{|path| path << "/.."}
+      ) if options[:ignore_data_with]
+
+      Path::Transaction.run @data, options do |t|
+        t.select(*options[:only_data])
+        t.delete(*options[:ignore_data])
+      end
+    end
+
+
     ##
     # Keep only specific data points from the data structure.
 
     def collect_data_points data_paths, affect_parent=false
+      Kronk::Cmd.warn "DataSet#collect_data_points deprecated. "+
+                      "Use Path::Transaction"
+
       new_data = @data.class.new
 
       [*data_paths].each do |data_path|
-        find_data data_path do |obj, k, path|
+        opts = Path.parse_regex_opts! data_path
+        data_path << "/.." if affect_parent
 
+        Path.find data_path, @data, opts do |data, k, path|
           curr_data     = @data
           new_curr_data = new_data
 
           path.each_with_index do |key, i|
-
-            if i == path.length - 1 && !affect_parent
-              new_curr_data[key] = curr_data[key]
-
-            elsif i == path.length - 2 && affect_parent
-              new_curr_data[key] = curr_data[key]
-              break
-
-            elsif path.length == 1 && affect_parent
-              new_data = curr_data
-              break
-
+            if i == path.length - 1
+              new_curr_data[key]   = curr_data[key]
             else
               new_curr_data[key] ||= curr_data[key].class.new
               new_curr_data        = new_curr_data[key]
@@ -82,7 +107,7 @@ class Kronk
         end
       end
 
-      @data = new_data
+      @data.replace new_data
     end
 
 
@@ -90,21 +115,18 @@ class Kronk
     # Remove specific data points from the data structure.
 
     def delete_data_points data_paths, affect_parent=false
-      [*data_paths].each do |data_path|
-        find_data data_path do |obj, k, path|
-
-          if affect_parent && data_at_path?(path)
-            @data = @data.class.new and return if path.length == 1
+      Kronk::Cmd.warn "DataSet#delete_data_points deprecated. "+
+                      "Use Path::Transaction"
 
-            parent_data = data_at_path path[0..-3]
-            del_method  = Array === parent_data ? :delete_at : :delete
+      [*data_paths].each do |data_path|
+        opts = Path.parse_regex_opts! data_path
+        data_path << "/.." if affect_parent
 
-            parent_data.send del_method, path[-2]
+        Path.find data_path, @data, opts do |obj, k, path|
+          next unless obj.respond_to? :[]
 
-          else
-            del_method = Array === obj ? :delete_at : :delete
-            obj.send del_method, k
-          end
+          del_method = Array === obj ? :delete_at : :delete
+          obj.send del_method, k
         end
       end
 
@@ -112,206 +134,11 @@ class Kronk
     end
 
 
-    ##
-    # Find specific data points from a nested hash or array data structure.
-    # If a block is given, will pass it any matched parent data object,
-    # key, and full path.
-    #
-    # Data points must be an Array or String with a glob-like format.
-    # Special characters are: / * = | \ and are interpreted as follows:
-    # :key/ - walk down tree by one level from key
-    # :*/key - walk down tree from any parent with key as a child
-    # :key1|key2 - return elements with key value of key1 or key2
-    # :key=val - return elements where key has a value of val
-    # :key\* - return root-level element with key "key*"
-    #
-    # Other examples:
-    #   find_data data, root/**=invalid|
-    #   # Returns an Array of grand-children key/value pairs
-    #   # where the value is 'invalid' or blank
-
-    def find_data data_path, curr_path=nil, data=nil, &block
-      curr_path ||= []
-      data      ||= @data
-
-      key, value, rec, data_path = parse_data_path data_path
-
-      yield_data_points data, key, value, rec, curr_path do |d, k, p|
-
-        if data_path
-          find_data data_path, p, d[k], &block
-        else
-          yield d, k, p
-        end
-      end
-    end
-
-
-    ##
-    # Checks if data is available at the given path.
-
-    def data_at_path? path
-      data_at_path path
-      true
-
-    rescue NoMethodError, TypeError
-      false
-    end
-
-
-    ##
-    # Retrieve the data at the given path array location.
-
-    def data_at_path path
-      curr = @data
-      path.each do |p|
-        raise TypeError, "Expected instance of Array or Hash" unless
-          Array === curr || Hash === curr
-        curr = curr[p]
-      end
-
-      curr
-    end
-
-
-    ##
-    # Parses a given data point and returns an array with the following:
-    # - Key to match
-    # - Value to match
-    # - Recursive matching
-    # - New data path value
-
-    def parse_data_path data_path
-      data_path  = data_path.dup
-      key        = nil
-      value      = nil
-      recursive  = false
-
-      until key && key != "**" || value || data_path.empty? do
-        value = data_path.slice!(%r{((.*?[^\\])+?/)})
-        (value ||= data_path).sub!(/\/$/, '')
-
-        data_path = nil if value == data_path
-
-        key   = value.slice! %r{((.*?[^\\])+?=)}
-        key, value = value, nil if key.nil?
-        key.sub!(/\=$/, '')
-
-        value = parse_path_item value if value
-
-        if key =~ /^\*{2,}$/
-          if data_path && !value
-            key, value, rec, data_path = parse_data_path(data_path)
-          else
-            key = /.*/
-          end
+    private
 
-          recursive = true
-        else
-          key = parse_path_item key
-        end
-      end
-
-      data_path = nil if data_path && data_path.empty?
-
-      [key, value, recursive, data_path]
-    end
-
-
-    ##
-    # Decide whether to make path item a regex, range, array, or string.
-
-    def parse_path_item str
-      if str =~ /(^|[^\\])([\*\?\|])/
-        str.gsub!(/(^|[^\\])(\*|\?)/, '\1.\2')
-        /^(#{str})$/i
-
-      elsif str =~ %r{^(\-?\d+)(\.{2,3})(\-?\d+)$}
-        Range.new $1.to_i, $3.to_i, ($2 == "...")
-
-      elsif str =~ %r{^(\-?\d+),(\-?\d+)$}
-        Range.new $1.to_i, ($1.to_i + $2.to_i), true
-
-      else
-        str.gsub "\\", ""
-      end
-    end
-
-
-    ##
-    # Yield data object and key, if a specific key or value matches
-    # the given data.
-
-    def yield_data_points data, mkey, mvalue=nil,
-                               recursive=false, path=nil, &block
-
-      return unless Hash === data || Array === data
-      path ||= []
-
-      each_data_item data do |key, value|
-        curr_path = path.dup << key
-
-        found = match_data_item(mkey, key) &&
-                match_data_item(mvalue, value)
-
-        yield data, key, curr_path if found
-        yield_data_points data[key], mkey, mvalue, true, curr_path, &block if
-          recursive
-      end
-    end
-
-
-    ##
-    # Check if data key or value is a match for nested data searches.
-
-    def match_data_item item1, item2
-      return if !item1.nil? && (Array === item2 || Hash === item2)
-
-      if item1.class == item2.class
-        item1 == item2
-
-      elsif Regexp === item1
-        item2.to_s =~ item1
-
-      elsif Range === item1
-        item1.include? item2.to_i
-
-      elsif item1.nil?
-        true
-
-      else
-        item2.to_s.downcase == item1.to_s.downcase
-      end
-    end
-
-
-    ##
-    # Universal iterator for Hash and Array objects.
-
-    def each_data_item data, &block
-      case data
-
-      when Hash
-        data.each(&block)
-
-      when Array
-        i = 0
-
-        # We need to iterate through the array this way
-        # in case items in it get deleted.
-
-        while i < data.length do
-          index = i
-          old_length = data.length
-
-          block.call index, data[index]
-
-          adj = old_length - data.length
-          adj = 0 if adj < 0
-
-          i = i.next - adj
-        end
-      end
+    def warn_path_deprecation!
+      Kronk::Cmd.warn "The :ignore_data_with and :only_data_with options "+
+                      "are deprecated. Use the '/..' path notation."
     end
   end
 end

data/lib/kronk/diff.rb

@@ -25,14 +25,17 @@ class Kronk
       when Hash
         output = "{\n"
 
+        sorted_keys = sort_any data.keys
+
         data_values =
-          data.map do |key, value|
-            pad = " " * indent
+          sorted_keys.map do |key|
+            value   = data[key]
+            pad     = " " * indent
             subdata = ordered_data_string value, struct_only, indent + 1
             "#{pad}#{key.inspect} => #{subdata}"
           end
 
-        output << data_values.sort.join(",\n") << "\n" unless data_values.empty?
+        output << data_values.join(",\n") << "\n" unless data_values.empty?
         output << "#{" " * indent}}"
 
       when Array
@@ -55,6 +58,64 @@ class Kronk
     end
 
 
+    ##
+    # Sorts an array of any combination of string, integer, or symbols.
+
+    def self.sort_any arr
+      i = 1
+      until i >= arr.length
+        j        = i-1
+        val      = arr[i]
+        prev_val = arr[j]
+
+        loop do
+          if smaller?(val, arr[j])
+            arr[j+1] = arr[j]
+            j = j - 1
+            break if j < 0
+
+          else
+            break
+          end
+        end
+
+        arr[j+1] = val
+
+        i = i.next
+      end
+
+      arr
+    end
+
+
+    ##
+    # Compares Numerics, Strings, and Symbols and returns true if the left
+    # side is 'smaller' than the right side.
+
+    def self.smaller? left, right
+      case left
+      when Numeric
+        case right
+        when Numeric then right > left
+        else              true
+        end
+
+      when Symbol
+        case right
+        when Numeric then false
+        when Symbol  then right.to_s > left.to_s
+        else              true
+        end
+
+      when String
+        case right
+        when String  then right > left
+        else              false
+        end
+      end
+    end
+
+
     ##
     # Adds line numbers to each lines of a String.
 
@@ -227,7 +288,7 @@ class Kronk
       while sequences.length > dist
         item = sequences.pop
         next unless item
-        item.each &block
+        item.each(&block)
       end
     end
 

data/lib/kronk/path.rb

@@ -0,0 +1,427 @@
+class Kronk
+
+  ##
+  # Finds specific data points from a nested Hash or Array data structure
+  # through the use of a file-glob-like path selector.
+  #
+  # Special characters are: "/ * ? = | \ . , \ ( )"
+  # and are interpreted as follows:
+  #
+  # :foo/ - walk down tree by one level from key "foo"
+  # :*/foo - walk down tree from any parent with key "foo" as a child
+  # :foo1|foo2 - return elements with key value of "foo1" or "foo2"
+  # :foo(1|2) - same behavior as above
+  # :foo=val - return elements where key has a value of val
+  # :foo\* - return root-level element with key "foo*" ('*' char is escaped)
+  # :**/foo - recursively search for key "foo"
+  # :foo? - return keys that match /\Afoo.?\Z/
+  # :2..10 - match any integer from 2 to 10
+  # :2...10 - match any integer from 2 to 9
+  # :2,5 - match any integer from 2 to 7
+  #
+  # Examples:
+  #
+  #   # Recursively look for elements with value "val" under top element "root"
+  #   Path.find "root/**=val", data
+  #
+  #   # Find child elements of "root" that have a key of "foo" or "bar"
+  #   Path.find "root/foo|bar", data
+  #
+  #   # Recursively find child elements of root whose value is 1, 2, or 3.
+  #   Path.find "root/**=1..3", data
+  #
+  #   # Recursively find child elements of root of literal value "1..3"
+  #   Path.find "root/**=\\1..3", data
+
+  class Path
+
+    # Used as path instruction to go up one path level.
+    module PARENT; end
+
+    # Used as path item value to match any key or value.
+    module ANY_VALUE; end
+
+    # Mapping of letters to Regexp options.
+    REGEX_OPTS = {
+      "i" => Regexp::IGNORECASE,
+      "m" => Regexp::MULTILINE,
+      "u" => (Regexp::FIXEDENCODING if defined?(Regexp::FIXEDENCODING)),
+      "x" => Regexp::EXTENDED
+    }
+
+    # 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 = "*?()|/"
+
+    # The path item delimiter character "/"
+    DCH = "/"
+
+    # The path character to assign value "="
+    VCH = "="
+
+    # The escape character to use any PATH_CHARS as its literal.
+    ECH = "\\"
+
+    # The Regexp escaped version of ECH.
+    RECH = Regexp.escape ECH
+
+    # The EndOfPath delimiter after which regex opt chars may be specified.
+    EOP = DCH + DCH
+
+    # The key string that represents PARENT.
+    PARENT_KEY = ".."
+
+    # The key string that indicates recursive lookup.
+    RECUR_KEY = "**"
+
+    # 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 = /(^|[^#{RECH}])([#{PATH_CHARS}])/
+
+
+    ##
+    # Instantiate a Path object with a String data path.
+    #   Path.new "/path/**/to/*=bar/../../**/last"
+
+    def initialize path_str, regex_opts=nil
+      path_str = path_str.dup
+      @path = self.class.parse_path_str path_str, regex_opts
+    end
+
+
+    ##
+    # Finds the current path in the given data structure.
+    # Returns a Hash of path_ary => data pairs for each match.
+    #
+    # If a block is given, yields the parent data object matched,
+    # the key, and the path array.
+    #
+    #   data = {:path => {:foo => :bar, :sub => {:foo => :bar2}}, :other => nil}
+    #   path = Path.new "path/**/foo"
+    #
+    #   all_args = []
+    #
+    #   path.find_in data |*args|
+    #     all_args << args
+    #   end
+    #   #=> {[:path, :foo] => :bar, [:path, :sub, :foo] => :bar2}
+    #
+    #   all_args
+    #   #=> [
+    #   #=>  [{:foo => :bar, :sub => {:foo => :bar2}}, :foo, [:path, :foo]],
+    #   #=>  [{:foo => :bar2}, :foo, [:path, :sub, :foo]]
+    #   #=> ]
+
+    def find_in data
+      matches = {[] => data}
+
+      @path.each_with_index do |(mkey, mvalue, recur), i|
+        args      = [matches, data, mkey, mvalue, recur]
+        last_item = i == @path.length - 1
+
+        self.class.assign_find(*args) do |sdata, key, spath|
+          yield sdata, key, spath if last_item && block_given?
+        end
+      end
+
+      matches
+    end
+
+
+    ##
+    # Fully streamed version of:
+    #   Path.new(str_path).find_in data
+    #
+    # See Path#find_in for usage.
+
+    def self.find path_str, data, regex_opts=nil, &block
+      matches = {[] => data}
+
+      parse_path_str path_str, regex_opts do |mkey, mvalue, recur, last_item|
+        assign_find matches, data, mkey, mvalue, recur do |sdata, key, spath|
+          yield sdata, key, spath if last_item && block_given?
+        end
+      end
+
+      matches
+    end
+
+
+    ##
+    # Common find functionality that assigns to the matches hash.
+
+    def self.assign_find matches, data, mkey, mvalue, recur
+      matches.keys.each do |path|
+        pdata = matches.delete path
+
+        if mkey == PARENT
+          path    = path[0..-2]
+          subdata = data_at_path path[0..-2], data
+
+          #!! Avoid yielding parent more than once
+          next if matches[path]
+
+          yield subdata, path.last, path if block_given?
+          matches[path] = subdata[path.last]
+          next
+        end
+
+        find_match pdata, mkey, mvalue, recur, path do |sdata, key, spath|
+          yield sdata, key, spath if block_given?
+          matches[spath] = sdata[key]
+        end
+      end
+    end
+
+
+    ##
+    # Returns the data object found at the given path array.
+    # Returns nil if not found.
+
+    def self.data_at_path path_arr, data
+      c_data = data
+
+      path_arr.each do |key|
+        c_data = c_data[key]
+      end
+
+      c_data
+
+    rescue NoMethodError, TypeError
+       nil
+    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 :each yielding a key/value pair.
+
+    def self.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 self.find_match data, mkey, mvalue=ANY_VALUE,
+                        recur=false, path=nil, &block
+
+      return [] unless Array === data || Hash === data
+
+      paths  = []
+      path ||= []
+
+      each_data_item data do |key, value|
+        c_path = path.dup << key
+
+        if match_data_item(mkey, key) && match_data_item(mvalue, value)
+          yield data, key, c_path if block_given?
+          paths << c_path
+        end
+
+        paths.concat \
+          find_match(data[key], mkey, mvalue, true, c_path, &block) if recur
+      end
+
+      paths
+    end
+
+
+    ##
+    # Check if data key or value is a match for nested data searches.
+
+    def self.match_data_item item1, item2
+      return if ANY_VALUE != item1 && (Array === item2 || Hash === item2)
+
+      if item1.class == item2.class
+        item1 == item2
+
+      elsif Regexp === item1
+        item2.to_s =~ item1
+
+      elsif Range === item1
+        item1.include? item2.to_i
+
+      elsif ANY_VALUE == item1
+        true
+
+      else
+        item2.to_s.downcase == item1.to_s.downcase
+      end
+    end
+
+
+    ##
+    # Decide whether to make path item matcher a regex, range, array, or string.
+
+    def self.parse_path_item str, regex_opts=nil
+      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
+
+      else
+        if String === str && (regex_opts || str =~ PATH_CHAR_MATCHER)
+
+          # Remove extra suffix characters
+          str.gsub! %r{(^|[^#{RECH}])(\*+\?+|\?+\*+)}, '\1*'
+          str.gsub! %r{(^|[^#{RECH}])\*+}, '\1*'
+
+          str = Regexp.escape str
+
+          # Remove escaping from special path characters
+          str.gsub! %r{#{RECH}([#{PATH_CHARS}])}, '\1'
+          str.gsub! %r{#{RECH}([#{RESC_CHARS}])}, '\1'
+          str.gsub! %r{(^|[^#{RECH}])([#{SUFF_CHARS}])}, '\1.\2'
+
+          Regexp.new "\\A(#{str})\\Z", regex_opts
+
+        elsif String === str
+          str.gsub %r{#{RECH}([^#{RECH}]|$)}, '\1'
+
+        else
+          str
+        end
+      end
+    end
+
+
+    ##
+    # Parses a path String into an Array of arrays containing
+    # matchers for key, value, and any special modifiers
+    # such as recursion.
+    #
+    #   Path.parse_path_str "/path/**/to/*=bar/../../**/last"
+    #   #=> [["path",ANY_VALUE,false],["to",ANY_VALUE,true],[/.*/,"bar",false],
+    #   #    [PARENT,ANY_VALUE,false],[PARENT,ANY_VALUE,false],
+    #   #    ["last",ANY_VALUE,true]]
+    #
+    # Note: Path.parse_path_str will slice the original path string
+    # until it is empty.
+
+    def self.parse_path_str path, regex_opts=nil
+      path = path.dup
+      regex_opts = parse_regex_opts! path, regex_opts
+
+      parsed = []
+
+      escaped   = false
+      key       = ""
+      value     = nil
+      recur     = false
+      next_item = false
+
+      until path.empty?
+        char = path.slice!(0..0)
+
+        case char
+        when DCH
+          next_item = true
+          char = ""
+
+        when VCH
+          value = ""
+          next
+
+        when ECH
+          escaped = true
+          next
+        end unless escaped
+
+        char = "#{ECH}#{char}" if escaped
+
+        if value
+          value << char
+        else
+          key << char
+        end
+
+        next_item = true if path.empty?
+
+        if next_item
+          next_item = false
+
+          if key == RECUR_KEY
+            key   = "*"
+            recur = true
+            key   = "" and next unless value || path.empty?
+
+          elsif key == PARENT_KEY
+            key = PARENT
+
+            if recur
+              key = "" and next unless value
+              key = "*"
+            end
+          end
+
+          unless key =~ /^\.?$/ && !value
+            parsed << [ parse_path_item(key, regex_opts),
+                        parse_path_item(value, regex_opts),
+                        recur ]
+
+            yield_args = (parsed.last.dup << path.empty?)
+
+            yield(*yield_args) if block_given?
+          end
+
+          key   = ""
+          value = nil
+          recur = false
+        end
+
+        escaped = false
+      end
+
+      parsed
+    end
+
+
+    ##
+    # Parses the tail end of a path String to determine regexp matching flags.
+
+    def self.parse_regex_opts! path, default=nil
+      opts = default || 0
+
+      return default unless
+         path =~ %r{[^#{RECH}]#{EOP}[#{REGEX_OPTS.keys.join}]+\Z}
+
+      path.slice!(%r{#{EOP}[#{REGEX_OPTS.keys.join}]+\Z}).to_s.
+        each_char{|c| opts |= REGEX_OPTS[c] || 0}
+
+      opts if opts > 0
+    end
+  end
+end