epitools 0.5.1 → 0.5.2

data/lib/epitools/core_ext/enumerable.rb

@@ -0,0 +1,306 @@
+
+
+module Enumerable
+
+  #
+  # 'true' if the Enumerable has no elements
+  #
+  def blank?
+    not any?
+  end
+
+  #
+  # `.all` is more fun to type than `.to_a`
+  #
+  alias_method :all, :to_a
+
+  #
+  # `includes?` is gramatically correct.
+  #
+  alias_method :includes?,  :include?
+
+  
+  #  
+  # Skip the first n elements and return an Enumerator for the rest, or pass them
+  # in succession to the block, if given. This is like "drop", but returns an enumerator
+  # instead of converting the whole thing to an array.
+  #
+  def skip(n)
+    if block_given?
+      each do |x|
+        if n > 0
+          n -= 1
+        else
+          yield x
+        end
+      end
+    else
+      enum_for :skip, n
+    end
+  end
+  
+  #
+  # Split this enumerable into chunks, given some boundary condition. (Returns an array of arrays.)
+  #
+  # Options:
+  #   :include_boundary => true  #=> include the element that you're splitting at in the results  
+  #                                  (default: false)
+  #   :after => true             #=> split after the matched element (only has an effect when used with :include_boundary)  
+  #                                  (default: false)
+  #   :once => flase             #=> only perform one split (default: false)
+  #
+  # Examples: 
+  #   [1,2,3,4,5].split{ |e| e == 3 }                           
+  #   #=> [ [1,2], [4,5] ]
+  #
+  #   [1,2,3,4,5].split(:include_boundary=>true) { |e| e == 3 } 
+  #   #=> [ [1,2], [3,4,5] ] 
+  #
+  #   chapters = File.read("ebook.txt").split(/Chapter \d+/, :include_boundary=>true)
+  #   #=> [ ["Chapter 1", ...], ["Chapter 2", ...], etc. ]
+  #
+  def split_at(matcher=nil, options={}, &block)
+    # TODO: Ruby 1.9 returns Enumerators for everything now. Maybe use that?
+    
+    return self unless self.any?
+    
+    include_boundary = options[:include_boundary] || false
+
+    if matcher.nil?
+      boundary_test_proc = block
+    else
+      if matcher.is_a? String or matcher.is_a? Regexp
+        boundary_test_proc = proc { |element| element[matcher] rescue nil }
+      else
+        boundary_test_proc = proc { |element| element == matcher }
+        #raise "I don't know how to split with #{matcher}"
+      end
+    end
+
+    chunks = []
+    current_chunk = []
+    
+    splits = 0
+    max_splits = options[:once] == true ? 1 : options[:max_splits]    
+
+    each do |e|
+
+      if boundary_test_proc.call(e) and (max_splits == nil or splits < max_splits)
+        
+        if current_chunk.empty? and not include_boundary 
+          next # hit 2 boundaries in a row... just keep moving, people!
+        end
+        
+        if options[:after]
+          # split after boundary
+          current_chunk << e        if include_boundary   # include the boundary, if necessary
+          chunks << current_chunk                         # shift everything after the boundary into the resultset
+          current_chunk = []                              # start a new result
+        else
+          # split before boundary
+          chunks << current_chunk                         # shift before the boundary into the resultset
+          current_chunk = []                              # start a new result
+          current_chunk << e        if include_boundary   # include the boundary, if necessary
+        end
+
+        splits += 1
+        
+      else
+        current_chunk << e
+      end
+
+    end
+    
+    chunks << current_chunk if current_chunk.any?
+
+    chunks # resultset
+  end
+
+  #
+  # Split the array into chunks, cutting between the matched element and the next element.
+  #
+  # Example:
+  #   [1,2,3,4].split_after{|e| e == 3 } #=> [ [1,2,3], [4] ]
+  #
+  def split_after(matcher=nil, options={}, &block)
+    options[:after]             ||= true
+    options[:include_boundary]  ||= true
+    split_at(matcher, options, &block)
+  end
+
+  #
+  # Split the array into chunks, cutting between the matched element and the previous element.
+  #
+  # Example:
+  #   [1,2,3,4].split_before{|e| e == 3 } #=> [ [1,2], [3,4] ]
+  #
+  def split_before(matcher=nil, options={}, &block)
+    options[:include_boundary]  ||= true
+    split_at(matcher, options, &block)
+  end
+
+  #
+  # Sum the elements
+  #  
+  def sum
+    if block_given?
+      inject(0) { |total,elem| total + yield(elem) }    
+    else
+      inject(0) { |total,elem| total + elem }
+    end
+  end
+  
+  #
+  # Average the elements
+  #
+  def average
+    count = 0
+    sum = inject(0) { |total,n| count += 1; total + n }
+    sum / count.to_f
+  end
+
+  #
+  # The same as "map", except that if an element is an Array or Enumerable, map is called
+  # recursively on that element.
+  #
+  # Example:
+  #   [ [1,2], [3,4] ].deep_map{|e| e ** 2 } #=> [ [1,4], [9,16] ] 
+  #
+  def deep_map(depth=nil, &block)
+    map do |obj|
+
+      case obj
+      when Enumerable
+        obj.deep_map(&block)
+      else
+        block.call(obj)
+      end
+
+    end
+  end
+  
+  alias_method :recursive_map,    :deep_map
+  alias_method :map_recursively,  :deep_map
+  alias_method :map_recursive,    :deep_map 
+
+  #
+  # The same as "select", except that if an element is an Array or Enumerable, select is called
+  # recursively on that element.
+  #
+  # Example:
+  #   [ [1,2], [3,4] ].deep_map{|e| e ** 2 } #=> [ [1,4], [9,16] ] 
+  #
+  def deep_select(depth=nil, &block)
+    select do |e|
+      if (e.is_a? Array or e.is_a? Enumerable) and (depth && depth > 0)
+        e.select(depth-1, &block)
+      else
+        block.call(e)
+      end
+    end
+  end
+  
+  alias_method :recursive_select, :deep_select
+  
+
+  #
+  # Identical to "reduce" in ruby1.9 (or foldl in haskell.)
+  #
+  # Example:
+  #   array.foldl{|a,b| a + b } == array[1..-1].inject(array[0]){|a,b| a + b }
+  #
+  def foldl(methodname=nil, &block)
+    result = nil
+
+    raise "Error: pass a parameter OR a block, not both!" unless !!methodname ^ block_given?
+      
+    if methodname
+      
+      each_with_index do |e,i|
+        if i == 0
+          result = e 
+          next
+        end
+        
+        result = result.send(methodname, e)      
+      end
+      
+    else
+      
+      each_with_index do |e,i|
+        if i == 0
+          result = e 
+          next
+        end
+        
+        result = block.call(result, e)      
+      end
+      
+    end
+    
+    result
+  end
+
+  #
+  # Returns the powerset of the Enumerable
+  #
+  # Example:
+  #   [1,2].powerset #=> [[], [1], [2], [1, 2]]
+  #
+  def powerset
+    # the bit pattern of the numbers from 0..2^(elements)-1 can be used to select the elements of the set...
+    a = to_a
+    (0...2**a.size).map do |bitmask|
+      a.select.with_index{ |e, i| bitmask[i] == 1 }
+    end
+  end
+
+  #
+  # Does the opposite of #zip -- converts [ [:a, 1], [:b, 2] ] to [ [:a, :b], [1, 2] ]
+  #  
+  def unzip
+    # TODO: make it work for arrays containing uneven-length contents
+    to_a.transpose
+  end
+  
+  #
+  # Associative grouping; groups all elements who share something in common with each other.
+  # You supply a block which takes two elements, and have it return true if they are "neighbours"
+  # (eg: belong in the same group). 
+  #
+  # Example:
+  #   [1,2,5,6].group_neighbours_by { |a,b| b-a <= 1 } #=> [ [1,2], [5,6] ]
+  #
+  # (Note: This is a very fast one-pass algorithm -- therefore, the groups must be pre-sorted.)
+  #
+  def group_neighbours_by(&block)
+    result = []
+    cluster = [first]
+    each_cons(2) do |a,b|
+      if yield(a,b)
+        cluster << b
+      else
+        result << cluster
+        cluster = [b]
+      end
+    end
+    
+    result << cluster if cluster.any?
+    
+    result    
+  end
+  alias_method :group_neighbors_by, :group_neighbours_by 
+  
+
+  #
+  # Convert the array into a stable iterator (Iter) object.
+  #
+  def to_iter
+    Iter.new(to_a)
+  end
+  alias_method :iter, :to_iter
+
+
+end
+
+

data/lib/epitools/core_ext/hash.rb

@@ -0,0 +1,201 @@
+
+class Hash
+
+  #
+  # 'true' if the Hash has no entries
+  #
+  def blank?
+    not any?
+  end
+  
+  #
+  # Runs "remove_blank_values" on self.
+  #  
+  def remove_blank_values!
+    delete_if{|k,v| v.blank?}
+    self
+  end
+  
+  #
+  # Returns a new Hash where blank values have been removed.
+  # (It checks if the value is blank by calling #blank? on it)
+  #
+  def remove_blank_values
+    dup.remove_blank_values!
+  end
+  
+  #
+  # Runs map_values on self. 
+  #  
+  def map_values!(&block)
+    keys.each do |key|
+      value = self[key]
+      self[key] = yield(value)
+    end
+    self
+  end
+  
+  #
+  # Transforms the values of the hash by passing them into the supplied
+  # block, and then using the block's result as the new value.
+  #
+  def map_values(&block)
+    dup.map_values!(&block)
+  end
+
+  #
+  # Runs map_keys on self.
+  #  
+  def map_keys!(&block)
+    keys.each do |key|
+      value = delete(key)
+      self[yield(key)] = value
+    end
+    self
+  end
+  
+  #
+  # Transforms the keys of the hash by passing them into the supplied block,
+  # and then using the blocks result as the new key.
+  #
+  def map_keys(&block)
+    dup.map_keys!(&block)
+  end
+
+  #
+  # Returns a new Hash whose values default to empty arrays. (Good for collecting things!)
+  #
+  # eg:
+  #   Hash.of_arrays[:yays] << "YAY!"
+  #
+  def self.of_arrays
+    new {|h,k| h[k] = [] }
+  end
+
+  #
+  # Returns a new Hash whose values default to 0. (Good for counting things!)
+  #
+  # eg:
+  #   Hash.of_integers[:yays] += 1
+  #
+  def self.of_integers
+    new(0)
+  end
+
+  #
+  # Hash keys become methods, kinda like OpenStruct. These methods have the lowest priority,
+  # so be careful. They will be overridden by any methods on Hash.
+  #
+  def self.lazy!
+    Hash.class_eval do
+      def method_missing(name, *args)
+        if args.any?
+          super
+        else
+          self[name] || self[name.to_s]
+        end
+      end
+    end
+  end  
+  
+  #
+  # `key?` and `includes?` is an alias for `include?`
+  #  
+  alias_method :key?,       :include?
+  alias_method :includes?,  :include?
+  
+  #
+  # Makes each element in the `path` array point to a hash containing the next element in the `path`.
+  # Useful for turning a bunch of strings (paths, module names, etc.) into a tree.
+  #
+  # Example:
+  #   h = {}
+  #   h.mkdir_p(["a", "b", "c"])    #=> {"a"=>{"b"=>{"c"=>{}}}}
+  #   h.mkdir_p(["a", "b", "whoa"]) #=> {"a"=>{"b"=>{"c"=>{}, "whoa"=>{}}}}
+  #
+  def mkdir_p(path)
+    return if path.empty?
+    dir = path.first
+    self[dir] ||= {}
+    self[dir].mkdir_p(path[1..-1])
+    self
+  end
+  
+  #
+  # Turn some nested hashes into a tree (returns an array of strings, padded on the left with indents.)
+  #
+  def tree(level=0, indent="  ")
+    result = []
+    dent = indent * level
+    each do |key, val|
+      result << dent+key
+      result += val.tree(level+1) if val.any?
+    end
+    result
+  end  
+  
+  #
+  # Print the result of `tree`
+  #
+  def print_tree
+    tree.each { |row| puts row }
+    nil
+  end  
+  
+  #
+  # Convert the hash into a GET query.
+  #
+  def to_query
+    params = ''
+    stack = []
+  
+    each do |k, v|
+      if v.is_a?(Hash)
+        stack << [k,v]
+      else
+        params << "#{k}=#{v}&"
+      end
+    end
+  
+    stack.each do |parent, hash|
+      hash.each do |k, v|
+        if v.is_a?(Hash)
+          stack << ["#{parent}[#{k}]", v]
+        else
+          params << "#{parent}[#{k}]=#{v}&"
+        end
+      end
+    end
+  
+    params.chop! # trailing &
+    params
+  end
+  
+  #
+  # Query a hash using MQL (see: http://wiki.freebase.com/wiki/MQL_operators for reference)
+  #
+  # Examples: 
+  #   > query(name: /steve/)
+  #   > query(/title/ => ??)
+  #   > query(articles: [{title: ??}])
+  #   > query(responses: [])
+  #   > query("date_of_birth<" => "2000")
+  #
+  def query(template)
+    results = [] 
+    template.each do |key,val|
+      case key
+      when Regexp, String
+      when Array
+      when Hash
+        results += hash.query(template)  
+      end
+    end
+    
+    map do |key,val|
+    end    
+  end
+  alias_method :mql, :query
+  
+end
+