qualitysmith_extensions 0.0.3

data/Readme

@@ -0,0 +1,72 @@
+== Our Extensions Readme
+
+== Introduction
+
+This is a library of miscellaneous general-purpose, reusable Ruby code, quite similar in purpose and layout to {Ruby Facets}[http://facets.rubyforge.org/], but it's certainly not meant to *compete* with it!
+
+Instead, developers are encouraged to first check if it the method or class they are looking for already exists in one of the fine existing open-source projects (like {Facets}[http://facets.rubyforge.org/] or {Extensions}[http://extensions.rubyforge.org/rdoc/index.html] or {stdlib}[http://www.ruby-doc.org/stdlib/]).
+
+If the code you are needing hasn't already been written by someone else, then you can throw it in this library. Also submit it to an existing extensions project if you think it's any good.
+
+Like Facets, this library contains:
+* methods that add functionality to existing Ruby classes (String, Array, etc.)
+* as well as new classes that aren't in core Ruby
+
+== Installation
+
+=== Non-gem
+
+Install the plugin from Subversion and add an svn:external to your vendor/plugins directory with this command:
+
+  ./script/plugin install -x http://code.qualitysmith.com/gemables/qualitysmith_extensions
+
+=== Gem
+
+In your dreams.
+
+== Usage
+
+=== In Rails (non-gem)
+
+Install the plugin from Subversion and add an svn:external to your vendor/plugins directory with this command:
+
+  ./script/plugin install -x http://code.qualitysmith.com/gemables/qualitysmith_extensions
+
+Put this in your config/environment.rb :
+
+ Rails::Initializer.run do |config|
+   config.load_paths += %W( #{RAILS_ROOT}/vendor/plugins )
+ end
+ require "qualitysmith_extensions/lib/qualitysmith_extensions/all.rb"
+
+=== Include as much or as little as you want
+
+To load everything:
+
+  require "../path/to/qualitysmith_extensions/lib/qualitysmith_extensions/all.rb"
+
+To load everything just for one class:
+
+  require "../path/to/qualitysmith_extensions/lib/qualitysmith_extensions/string/all.rb"
+
+To load just an individual method:
+
+  require "../path/to/qualitysmith_extensions/lib/qualitysmith_extensions/array/average.rb"
+
+=== Gem
+
+It's not packaged as a gem yet,... but if it were, it might work something like this?:
+
+  require "rubygems"
+  require_gem "qualitysmith_extensions"
+  require "qualitysmith_extensions/lib/qualitysmith_extensions/array/all.rb"
+
+== Running tests
+
+Tests are self-contained within the file for the code that is under test.
+
+To run the tests directly, you need to use the <tt>rubytest</tt> command that is included with the {Reap}[http://reap.rubyforge.org/] tool.
+
+If you use <tt>vim</tt>, you can set up your editor to run the tests just by typing the <tt>:Test</tt> command. To set that up, just include <tt>~/svn/devscripts/vim/include.vim</tt> .
+
+At some point in time, we may extract them into separate files using the Reap test extractor tool.

data/lib/qualitysmith_extensions/all.rb

@@ -0,0 +1,2 @@
+require File.dirname(__FILE__) + "/kernel/require_all"
+require_all File.dirname(__FILE__), :exclude => /[^|\/]test\//, :exclude_files => 'all.rb'

data/lib/qualitysmith_extensions/array/all.rb

@@ -0,0 +1,2 @@
+require File.dirname(__FILE__) + "/../kernel/require_all"
+require_all File.dirname(__FILE__), :exclude_files => 'all.rb'

data/lib/qualitysmith_extensions/array/average.rb

@@ -0,0 +1,42 @@
+# Author::    Tyler Rick
+# Copyright:: Copyright (c) 2007 QualitySmith, Inc.
+# License::   Ruby License
+# Submit to Facets?:: Yes.
+#   Wait, so Facets has mode (http://facets.rubyforge.org/src/doc/rdoc/core/classes/Enumerable.html#M001253) but it doesn't have mean/average?
+#   Whether or not this Array#average is included, Facets ought to have an Enumerable#mean/average similar to mode that uses each iterator rather than Array#size. (Still might want to keep this version if it's more efficient for Arrays?)
+
+class Array
+  # Calculates the arithmetic average (mean) of the elements in the array as a <tt>Float</tt>.
+  #   irb -> [1, 3, 3].average
+  #       => 2.33333333333333
+  def average
+    if self.size == 0
+      raise ZeroDivisionError
+    end
+    self.inject(0.0) do |sum, item|
+      sum + item.to_f
+    end / self.size
+  end
+end
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+=begin test
+require 'test/unit'
+class TheTest < Test::Unit::TestCase
+  def test_average
+    assert_equal 2, [0, 4].average
+    assert_equal Float, [0, 4].average.class
+
+    assert_equal 2.5, [0, 5].average
+
+    assert_raise ZeroDivisionError do
+      [].average
+    end
+  end
+end
+=end

data/lib/qualitysmith_extensions/array/expand_ranges.rb

@@ -0,0 +1,48 @@
+# Author::    Tyler Rick
+# Copyright:: Copyright (c) 2007 QualitySmith, Inc.
+# License::   Ruby License
+# Submit to Facets?:: Yes.
+
+require 'rubygems'
+require 'facets/core/kernel/silence_warnings'
+
+class Array
+  # Expands (calls to_a on) all Ranges contained in this array, replacing the range with the list of elements that the range represents.
+  #
+  #   [1..3, 5..7].expand_ranges
+  #   => [1, 2, 3, 5, 6, 7]
+  #
+  def expand_ranges
+    new_array = []
+    each do |item|
+      silence_warnings do             # Object.to_a: warning: default `to_a' will be obsolete
+        if item.respond_to?(:to_a)
+          new_array.concat item.to_a
+        else
+          new_array.concat [item]
+        end
+      end
+    end
+    new_array
+  end
+end
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+=begin test
+require 'test/unit'
+class TheTest < Test::Unit::TestCase
+  def test_1
+    assert_equal [1, 2, 3], [1, 2, 3].expand_ranges
+  end
+  def test_2
+    assert_equal [1, 2, 3], [1..3].expand_ranges
+    assert_equal [1, 2, 3, 5, 6, 7], [1..3, 5..7].expand_ranges
+  end
+end
+=end
+

data/lib/qualitysmith_extensions/array/group_by.rb

@@ -0,0 +1,112 @@
+# Author::    Tyler Rick
+# Copyright:: Copyright (c) 2007 QualitySmith, Inc.
+# License::   Ruby License
+# Submit to Facets?:: Yes
+# Developer notes:
+# * Name is too general? Name it something to do with 'tables'?
+
+require 'rubygems'
+require_gem 'facets'
+require 'facet/array/delete_values_at'
+require 'facet/array/to_hash'
+class Array
+
+=begin rdoc
+   Breaks an array into a hash of smaller arrays, making a new group for each unique value in the specified column. Each unique value becomes a key in the hash.
+
+   Example:
+        [
+           ['a', 1],
+           ['a', 2],
+           ['b', 3],
+           ['b', 4],
+        ].group_by(0)
+    =>  
+        "a"=>[[1], [2]], 
+        "b"=>[[3], [4]]
+
+   Options:
+   * <tt>delete_key</tt>: deletes the key from the corresponding array if true (default true)
+
+   Example:
+        [
+           ['a', 1],
+           ['a', 2],
+           ['b', 3],
+           ['b', 4],
+        ].group_by(0, :delete_key => false)
+    =>  
+        "a"=>[['a', 1], ['a', 2]], 
+        "b"=>[['b', 3], ['b', 4]]
+   
+   Notes:
+   * <tt>self</tt> must be in the shape of a "table" (a non-sparse, rectangular, two-dimensional array).
+   * This is different from the GROUP BY in SQL in that it doesn't apply an aggregate (like sum or average) to each group -- it just returns each group unmodified.
+
+=end
+  def group_by(column_index, *args)
+    options = (if args.last.is_a?(Hash) then args.pop else {} end)
+    hash = {}
+    self.each do |row|
+      row_to_keep = row.dup
+      row_to_keep.delete_values_at(column_index) unless options[:delete_key] == false
+
+      hash[row[column_index]] ||= []
+      hash[row[column_index]] << row_to_keep
+    end
+    hash
+  end
+end
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+=begin test
+class TheTest < Test::Unit::TestCase
+  def test_group_by
+    assert_equal({ }, [ ].group_by(column_index = 0))
+
+    assert_equal({
+        "a"=>[[1], [2]], 
+        "b"=>[[3], [4]]
+      }, [
+        ['a', 1],
+        ['a', 2],
+        ['b', 3],
+        ['b', 4],
+      ].group_by(column_index = 0)
+    )
+    assert_equal({
+        "a"=>[['a', 1], ['a', 2]], 
+        "b"=>[['b', 3], ['b', 4]]
+      }, [
+        ['a', 1],
+        ['a', 2],
+        ['b', 3],
+        ['b', 4],
+      ].group_by(column_index = 0, :delete_key => false)
+    )
+
+    input = [
+      ['Bob', "Bottle of water", 1.00],
+      ['Bob', "Expensive stapler", 50.00],
+      ['Alice', "Dinner for 2", 100.00],
+      ['Alice', "Bus ride to RubyConf", 50.00],
+    ]
+    assert_equal({
+        "Alice"=>[["Dinner for 2", 100.0], ["Bus ride to RubyConf", 50.0]],
+        "Bob"=>[["Bottle of water", 1.0], ["Expensive stapler", 50.0]]
+      }, input.group_by(column_index = 0)
+    )
+    assert_equal({
+        50.0=>[["Bob", "Expensive stapler"], ["Alice", "Bus ride to RubyConf"]],
+        100.0=>[["Alice", "Dinner for 2"]],
+        1.0=>[["Bob", "Bottle of water"]]
+      }, input.group_by(column_index = 2)
+    )
+  end
+end
+=end

data/lib/qualitysmith_extensions/array/sequence.rb

@@ -0,0 +1,64 @@
+# Author::    Lance Ivy
+# Copyright:: Copyright (c) 2007 QualitySmith, Inc.
+# License::   Ruby License
+# Submit to Facets?:: Not sure.
+
+class Array
+=begin rdoc
+  Returns the value previous to the given value. The value previous to the first is the last. Returns nil if the given value is not in the array.
+
+  Example:
+       sequence = ['a', 'b', 'c']
+       sequence.before('a')           => 'c'
+       sequence.before('b')           => 'a'
+       sequence.before('c')           => 'b'
+       sequence.before('d')           => nil
+=end
+  def before(value)
+    return nil unless include? value
+    self[(index(value).to_i - 1) % length]
+  end
+
+=begin rdoc
+  Returns the value after the given value. The value before the last is the first. Returns nil if the given value is not in the array.
+
+  Example:
+       sequence = ['a', 'b', 'c']
+       sequence.after('a')           => 'b'
+       sequence.after('b')           => 'c'
+       sequence.after('c')           => 'a'
+       sequence.after('d')           => nil
+=end
+  def after(value)
+    return nil unless include? value
+    self[(index(value).to_i + 1) % length]
+  end
+end
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+=begin test
+class TheTest < Test::Unit::TestCase
+  def setup
+    @sequence = ['a', 'b', 'c']
+  end
+
+  def test_before
+    assert_equal 'c', @sequence.before('a')
+    assert_equal 'a', @sequence.before('b')
+    assert_equal 'b', @sequence.before('c')
+    assert_equal nil, @sequence.before('d')
+  end
+
+  def test_after
+    assert_equal 'b', @sequence.after('a')
+    assert_equal 'c', @sequence.after('b')
+    assert_equal 'a', @sequence.after('c')
+    assert_equal nil, @sequence.after('d')
+  end
+end
+=end

data/lib/qualitysmith_extensions/array/shell_escape.rb

@@ -0,0 +1,34 @@
+# Author::    Tyler Rick
+# Copyright:: Copyright (c) 2007 QualitySmith, Inc.
+# License::   Ruby License
+# Submit to Facets?:: Yes. Symbol#to_proc -> Facets
+
+require 'rubygems'
+require 'extensions/symbol' unless Symbol.method_defined?(:to_proc)
+require 'facets/core/kernel/require_local'
+require_local '../string/shell_escape.rb'
+
+class Array
+  def shell_escape
+    self.map(&:shell_escape)
+  end
+end
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+=begin test
+require 'test/unit'
+class TheTest < Test::Unit::TestCase
+  def test_1
+    assert_equal ['a'], ['a'].shell_escape
+  end
+  def test_2
+    assert_equal ["arg1", "'multiple words for single argument'"],
+                 ['arg1',  'multiple words for single argument'].shell_escape
+  end
+end
+=end

data/lib/qualitysmith_extensions/array/to_a_recursive.rb

@@ -0,0 +1,39 @@
+# Author::    Tyler Rick
+# Copyright:: Copyright (c) 2007 QualitySmith, Inc.
+# License::   Ruby License
+# Submit to Facets?:: Yes.
+
+class Array
+  
+  # A lot like array.flatten, except that it will also "flatten" ranges (by converting range to range.to_a) and any other objects that respond to to_a contained in the array in addition to arrays contained in the array.
+  # Compare with Array#expand_ranges
+  def to_a_recursive
+    map do |item|
+      # Assume that all arrays contain only elements that do not respond to to_a_recursive or arrays.
+      if item.respond_to? :to_a_recursive
+        item.to_a_recursive
+      else
+        item.to_a
+      end
+    end
+  end
+end
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+=begin test
+require 'test/unit'
+class TheTest < Test::Unit::TestCase
+  def test_1
+    assert_equal [[1, 2, 3], [5, 6, 7]], [1..3, 5..7].to_a_recursive
+  end
+  def test_2
+    assert_equal [[1, 2, 3], [ [5, 6, 7], [9, 10] ] ], [1..3, [5..7, 9..10]].to_a_recursive
+  end
+end
+=end
+

data/lib/qualitysmith_extensions/array/to_query_string.rb

@@ -0,0 +1,94 @@
+# Author::    Anthony Kaufman, Tyler Rick
+# Copyright:: Copyright (c) 2007 QualitySmith, Inc.
+# License::   Ruby License
+# Submit to Facets?:: Yes.
+
+autoload :CGI, 'cgi'
+class Array
+
+=begin rdoc
+  Converts into a string that can be used as the {query string}[http://en.wikipedia.org/wiki/Query_string] of a URL (for example, <tt>?key[]=val1&key[]=val2</tt>).
+
+  Example:
+    [
+      'Fred',
+      'Sam'
+    ].to_query_string('names')
+    ==> "names[]=Fred&names[]=Sam"
+
+  <tt>key</tt> is the name of the key in params that will receive the array when you load the page. So, for example, if you go to page with this query string (key = "names"): <tt>?names[]=Fred&names[]=Sam</tt>, params will be have a key "names", like so: <tt>{"names"=>["Fred", "Sam"]}</tt>.
+=end
+  def to_query_string(key)
+    elements = []
+    
+    self.each do |value|
+      _key = key + '[]'
+      if value.is_a? Array
+        raise "Array#to_query_string only works on flat (1-dimensional) arrays."
+      elsif value.respond_to? :to_query_string
+      	value = value.to_query_string(_key)
+      else
+        value = CGI.escape value.to_s
+      end
+      elements << _key + '=' + value
+    end
+    
+    elements.join('&')
+  end
+end
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+=begin test
+class TheTest < Test::Unit::TestCase
+  #-------------------------------------------------------------------------------------------------
+  # Array:
+
+  def test_array_to_query_string_trivial
+    data = []
+    assert_equal '', data.to_query_string('names')
+  end
+
+  def test_array_to_query_string_basic
+    data = [
+      'Fred',
+      'Sam'
+    ]
+    assert_equal 'names[]=Fred&names[]=Sam', data.to_query_string('names')
+  end
+  
+  def test_array_to_query_string_encoding
+    data = ['f&r', 'a w$']
+    
+    assert_equal 'foo[]=f%26r&foo[]=a+w%24', data.to_query_string('foo')
+  end
+
+  def test_array_to_query_string_nesting
+    data = [
+        [
+          'Wilma',
+          'Sara'
+        ],
+        [
+          'Fred',
+          'Sam'
+        ]
+      ]
+    assert_raise RuntimeError do data.to_query_string('names') end
+  end
+end
+=end
+
+=begin examples
+require 'irb/xmp'
+xmp <<End
+    [
+      'Fred',
+      'Sam'
+    ].to_query_string('names')
+End
+=end

data/lib/qualitysmith_extensions/collection_extensions_for_cgi.rb

@@ -0,0 +1,2 @@
+require File.dirname(__FILE__) + '/hash/to_query_string.rb'
+require File.dirname(__FILE__) + '/array/to_query_string.rb'