sixarm_ruby_ramp 2.1.0

data/lib/sixarm_ruby_ramp/hash.rb

@@ -0,0 +1,238 @@
+# -*- coding: utf-8 -*-
+
+require 'yaml'
+
+# Hash extensions
+
+class Hash
+
+
+  # @return [Boolean] true if size > 0
+
+  def size?
+    size>0
+  end
+
+  # @return [Hash] a new hash sorted by the keys
+  #
+  # @example
+  #    h = {"c" => "cherry", "b" => "banana", "a" =>"apple" }
+  #    h.sort_keys => {"a" => "apple", "b" => "banana", "c" => "cherry"}
+
+  def sort_by_keys
+    Hash[sort]
+  end
+
+  
+  # Calls block once for each key in hsh, passing the key and value to the block as a two-element array.
+  #
+  # The keys are sorted.
+  #
+  # @example
+  #   h = { "xyz" => "123", "abc" => "789" }
+  #   h.each_sort {|key, val| ... }
+  #   => calls the block with "abc" => "789", then with "xyz" => "123"
+
+  def each_sort
+    keys.sort.each{|key| yield key,self[key] }
+  end
+
+
+  # Calls block once for each key in hsh, 
+  # passing the key as a parameter,
+  # and updating it in place.
+  #
+  # @example
+  #   h = { "a" => "b", "c" => "d" }
+  #   h.each_key! {|key| key.upcase }
+  #   h => { "A" => "b", "C" => "d" }
+  #
+  # @return self
+
+  def each_key!
+    replacements=[]
+    keys.each{|key|
+      value=self[key]
+      key2=yield(key)
+      if key===key2
+        #nop
+      else
+        replacements << [key,key2,value]
+      end
+    }
+    replacements.each{|key,key2,value|
+      self.delete(key)
+      self[key2]=value
+    }
+    return self
+  end
+
+
+  # Calls block once for each key in hsh,
+  # passing the key and value as parameters,
+  # and updated them in place.
+  #
+  # @example
+  #   h = { "a" => "b", "c" => "d" }
+  #   h.each_pair! {|key,value| key.upcase, value.upcase }
+  #   h => { "A" => "B", "C" => "D" }
+  #
+  # @return self.
+
+  def each_pair!
+    replacements=[]
+    keys.each{|key|
+      value=self[key]
+      key2,value2=yield(key,value)
+      if key===key2
+        if value===value2
+          #nop
+        else
+          self[key]=value2
+        end
+      else
+        replacements << [key,key2,value2]
+      end
+    }
+    replacements.each{|key,key2,value2|
+      self.delete(key)
+      self[key2]=value2
+    }
+    return self
+  end
+
+
+  # Calls block once for each key in hsh,
+  # passing the value as a parameter, 
+  # and updating it in place.
+  #
+  # @example
+  #   h = { "a" => "b", "c" => "d" }
+  #   h.each_value! {|value| value.upcase }
+  #   h => { "a" => "B", "c" => "d" }
+  #
+  # @return self.
+
+  def each_value!
+    keys.each{|key|
+      value=self[key]
+      value2=yield(value)
+      if value===value2
+        #nop
+      else
+        self[key]=yield(value) 
+      end
+    }
+    return self
+  end
+
+
+  # Calls block once for each key-value pair in hsh,
+  # passing the key and value as paramters to the block.
+  #
+  # @example
+  #   h = {"a"=>"b", "c"=>"d", "e"=>"f" }
+  #   h.map_pair{|key,value| key+value }
+  #   => ["ab","cd","ef"]
+
+  def map_pair
+    keys.map{|key| yield key, self[key] }
+  end
+
+
+  # Hash#pivot aggregates values for a hash of hashes,
+  # for example to calculate subtotals and groups.
+  #
+  # Suppose you have data arranged by companies, roles, and headcounts.
+  #
+  #     data = {
+  #     "Apple"     => {"Accountants" => 11, "Designers" => 22, "Developers" => 33},
+  #     "Goggle"    => {"Accountants" => 44, "Designers" => 55, "Developers" => 66},
+  #     "Microsoft" => {"Accountants" => 77, "Designers" => 88, "Developers" => 99},
+  #   }
+  # 
+  # To calculate each company's total headcount, you pivot up, then sum:
+  # 
+  #   data.pivot(:up,&:sum)
+  #   => {
+  #    "Apple"=>66, 
+  #    "Goggle"=>165, 
+  #    "Microsoft"=>264
+  #   }
+  # 
+  # To calculate each role's total headcount, you pivot down, then sum:
+  # 
+  #   data.pivot(:down,&:sum)
+  #   => {
+  #    "Accountants"=>132,
+  #    "Designers"=>165,
+  #    "Developers"=>198
+  #   }
+  # 
+  #  Generic xxample:
+  #   h={
+  #    "a"=>{"x"=>1,"y"=>2,"z"=>3},
+  #    "b"=>{"x"=>4,"y"=>5,"z"=>6},
+  #    "c"=>{"x"=>7,"y"=>8,"z"=>9},
+  #   }
+  #   h.pivot(:keys) => {"a"=>[1,2,3],"b"=>[4,5,6],"c"=>[7,8,9]} 
+  #   h.pivot(:vals) => {"x"=>[1,4,7],"y"=>[2,5,8],"z"=>[3,6,9]}
+  #
+  # = Calculating subtotals
+  #
+  # The pivot method is especially useful for calculating subtotals.
+  #
+  # @example
+  #   r = h.pivot(:keys)
+  #   r['a'].sum => 6
+  #   r['b'].sum => 15
+  #   r['c'].sum => 24
+  #
+  # @example
+  #   r=h.pivot(:vals)
+  #   r['x'].sum => 12
+  #   r['y'].sum => 15
+  #   r['z'].sum => 18
+  #
+  # = Block customization
+  #
+  # You can provide a block that will be called for the pivot items.
+  #
+  # @example
+  #   h.pivot(:keys){|items| items.max } => {"a"=>3,"b"=>6,"c"=>9}
+  #   h.pivot(:keys){|items| items.join("/") } => {"a"=>"1/2/3","b"=>"4/5/6","c"=>"7/8/9"}
+  #   h.pivot(:keys){|items| items.inject{|sum,x| sum+=x } } => {"a"=>6,"b"=>15,"c"=>24}
+  #
+  # @example
+  #   h.pivot(:vals){|items| items.max } => {"a"=>7,"b"=>8,"c"=>9}
+  #   h.pivot(:vals){|items| items.join("-") } => {"a"=>"1-4-7","b"=>"2-5-8","c"=>"3-6-9"}
+  #   h.pivot(:vals){|items| items.inject{|sum,x| sum+=x } } => {"a"=>12,"b"=>15,"c"=>18}   
+
+  def pivot(direction='keys',&block)
+    a=self.class.new
+    direction=direction.to_s
+    up=pivot_direction_up?(direction)
+    each_pair{|k1,v1|
+      v1.each_pair{|k2,v2|
+        k = up ? k1 : k2
+        a[k]=[] if (a[k]==nil or a[k]=={})
+        a[k]<<(v2)
+      }
+    }
+    if block
+      a.each_pair{|key,val| a[key]=block.call(val)}
+    end
+    a
+  end
+
+  protected
+
+  def pivot_direction_up?(direction_name)
+    case direction_name.to_s
+    when 'key','keys','up','left','out' then return true
+    when 'val','vals','down','right','in' then return false
+    else raise ArgumentError.new('Pivot direction must be either: key/keys/up/left/out or val/vals/down/right/in')
+    end
+  end
+
+end

data/lib/sixarm_ruby_ramp/integer.rb

@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+
+# Integer extensions
+
+class Integer
+
+  # Syntactic sugar to yield n times to a block.
+  #
+  # Comparison to Integer#times: 
+  # Integer#maps is similar to Integer#times except that the output from each
+  # call to the block is captured in an array element and that array is
+  # returned to the calling code.
+  #
+  # @return an array of any results
+  #
+  # @example Generate an array of three random numbers
+  #   3.maps{rand}
+  #   => [0.0248131784304143, 0.814666170190905, 0.15812816258206]
+  #
+  
+  def maps
+    return (0...self).map{|item| yield item}
+  end
+
+
+end

data/lib/sixarm_ruby_ramp/io.rb

@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*-
+
+# IO extensions
+
+class IO
+
+
+  # Reads the entire file specified by name as individual lines as with IO#readlines,
+  # and returns those lines in an array of rows, where each row is an array of fields.
+  #
+  # @return [Array<Array<String>>] an array of rows, where each row is an array of fields.
+  #
+  # @example
+  #   IO.readrows("my.tsv")
+  #    => [["A1","B1","C1"],["A2","B2","C2"],["A3","B3","C3"]]
+  #
+  # @param [String] filename
+  # @param [Hash] options
+  #   - Rows are separated by _row_ option, which defaults to Ruby's record separator $/ or "\n" 
+  #   - Cols are separated by _col_ option, which defaults to Ruby's string split separator $; or "\t"
+  #
+  # @example with options suitable for a file using TSV (Tab Separated Values)
+  #   IO.readrows("my.tsv", :row=>"\n", :col=>"\t") 
+  #
+  # Note: the col option is sent along to String#split, so can be a string or a regexp.
+  #
+  # @see
+  # - File#readline
+  # - File#readlines
+  # - File#readrow
+
+  def IO.readrows(filename, options={})
+    row_sep||=options[:row]||$/||"\n"
+    col_sep||=options[:col]||$;||"\t"
+    return IO.readlines(filename, row_sep).map{|line| line.chomp(row_sep).split(col_sep)}
+  end
+
+
+  # Read a line as with IO#readline and return the line as a row of fields.
+  #
+  # Note: the col option is sent along to String#split, so can be a string or a regexp.
+  #
+  # @return [Array<String>] fields
+  #
+  # @param [Hash] options
+  # - Rows are separated by _row_ option, which defaults to Ruby's record separator $/ or "\n" 
+  # - Cols are separated by _col_ option, which defaults to Ruby's string split separator $; or "\t"
+  #
+  # @example
+  #   file = File.new("my.tsv")
+  #   file.readrow() => ["A1","B1","C1"]
+  #   file.readrow() => ["A2","B2","C2"]
+  #   file.readrow() => ["A3","B3","C3"]]
+  #
+  # @example with options suitable for a file using TSV (Tab Separated Values)
+  #   file = File.new("my.tsv")
+  #   file.readrow(:row=>"\n", :col=>"\t") => ["A1","B1","C1"] 
+  #   file.readrow(:row=>"\n", :col=>"\t") => ["A2","B2","C2"] 
+  #   file.readrow(:row=>"\n", :col=>"\t") => ["A3","B3","C3"] 
+  #
+  # @see File#readline
+  # @see File#readlines
+  # @see File#readrows
+
+  def readrow(options={})
+    row_sep||=options[:row]||$/||"\n"
+    col_sep||=options[:col]||$;||"\t"
+   return readline(row_sep).chomp(row_sep).split(col_sep)
+  end
+
+end

data/lib/sixarm_ruby_ramp/kernel.rb

@@ -0,0 +1,84 @@
+# -*- coding: utf-8 -*-
+require 'pp'
+require 'stringio'  
+
+# Kernel extensions
+
+module Kernel
+
+  # See:
+  # - http://www.ruby-forum.com/topic/75258
+  # - In 1.9 (Ruby CVS HEAD) there is #__method__ and #__callee__
+  # - http://eigenclass.org/hiki.rb?Changes+in+Ruby+1.9#l90
+  #-
+  # Make this fast because its often doing logging & reporting.
+  # Inline this and use $1 because it's empirically faster than /1
+  #
+  # These two methods are always equal:
+  #   caller_method_name(0) === my_method_name
+  #
+  # @example
+  #   def foo
+  #     puts my_method_name
+  #   end
+  #   foo
+  #   => "foo"
+  #
+  # @return [String] my method name
+
+  def my_method_name
+    caller[0] =~ /`([^']*)'/ and $1
+  end
+
+
+  # See:
+  # - http://www.ruby-forum.com/topic/75258
+  # - In 1.9 (Ruby CVS HEAD) there is #__method__ and #__callee__
+  # - http://eigenclass.org/hiki.rb?Changes+in+Ruby+1.9#l90
+  #-
+  # Make this fast because its often doing logging & reporting.
+  # Inline this and use $1 because it's empirically faster than /1
+  #
+  # These two methods are always equal:
+  #   caller_method_name(0) === my_method_name
+  #
+  # @example
+  #   def foo
+  #     puts caller_method_name(0)
+  #     puts caller_method_name(1)
+  #   end
+  #   => 
+  #   "foo"
+  #   "irb_binding"
+  #
+  # @return [String] the method name of the caller at the index
+
+  def caller_method_name(caller_index=0)
+    caller[caller_index] =~ /`([^']*)'/ and $1
+  end
+
+  
+  # Pretty print to a string.
+  # 
+  # Created by Graeme Mathieson.
+  #
+  # See http://rha7dotcom.blogspot.com/2008/07/ruby-and-rails-how-to-get-pp-pretty.html
+  #
+  # @example
+  #   pp_s(["foo","goo"])
+  #   => "[\"foo\", \"goo\"]\n"
+  #
+  # @return [String] a pretty print string of the params
+
+  def pp_s(*objs)  
+    str = StringIO.new  
+    objs.each {|obj|  
+        PP.pp(obj, str)  
+      }  
+      str.rewind  
+      str.read  
+  end  
+  module_function :pp_s  
+
+end
+

data/lib/sixarm_ruby_ramp/math.rb

@@ -0,0 +1,30 @@
+# -*- coding: utf-8 -*-
+
+# Math extensions
+
+module Math
+
+
+  # @return [Float] the natural log of _num_
+  #
+  # @example
+  #   Math.ln(2.719)
+  #   => 1.00
+
+  def Math.ln(num)
+   Math.log(num)
+  end
+
+
+  # @return [Float] the log of _num_ in base _base_
+  #
+  # @example
+  #   Math.logn(10000,10) 
+  #   => 4.00
+ 
+  def Math.logn(num,base)
+    Math.ln(num)/Math.ln(base)
+  end
+
+
+end

data/lib/sixarm_ruby_ramp/nil.rb

@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+
+# NilClass provides an instantiatable object
+# suitable for more careful thorough programming.
+
+class NilClass
+
+ # @return [true]
+ 
+ def blank?
+  return true
+ end
+
+
+ # @return [false]
+
+ def size?
+  return false
+ end
+
+end
+

data/lib/sixarm_ruby_ramp/numeric.rb

@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+
+# Numeric extensions
+
+class Numeric
+
+
+ # @return 0 if the given flag is any of: nil, false, 0, [], {}
+ #
+ # @example
+ #   3.if(true) => 3
+ #   3.if(false) => 0
+ #   
+
+ def if(flag)
+   if [nil,false,0,[],{}].include?(flag) then 0 else self end
+ end
+
+
+ # @return self if flag is nil, false, 0, [], {}; otherwise return 0.
+ #
+ # @example
+ #   3.unless(true) => 0
+ #   3.unless(false) => 3
+
+ def unless(flag)
+   if [nil,false,0,[],{}].include?(flag) then self else 0 end
+ end
+
+
+ # @return self as a percent, i.e. * 100 then call round.
+ #
+ # @example
+ #   x = 0.12345
+ #   x.percent => 12
+ #   x.percent(1) => 12.3
+ #   x.percent(2) => 12.34
+ #   x.percent(-1) => 10
+
+ def percent(ndigits=0)
+  (self * 100).round(ndigits)
+ end
+
+end

data/lib/sixarm_ruby_ramp/object.rb

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+
+# Object extensions
+
+class Object
+
+  # Syntactic sugar for arrays.
+  #
+  # Definition:
+  #   object.in? array === array.include? object
+  #
+  # @example
+  #   array=['a','b','c']
+  #   object='b'
+  #   object.in? array 
+  #   => true
+  #
+  # @return [Boolean] true iff this object is included in the array.
+  def in?(array)
+    array.include?(self)
+  end
+  
+end