webget_ruby_ramp 1.7.2

data/lib/webget_ruby_ramp.rb

@@ -0,0 +1,250 @@
+=begin rdoc
+
+= WebGet Ruby Gem: Ramp is a toolkit of methods to ramp up your Ruby On Rails applications
+
+Author:: Joel Parker Henderson, joelparkerhenderson@gmail.com
+Copyright:: Copyright (c) 2006-2010 Joel Parker Henderson
+License:: CreativeCommons License, Non-commercial Share Alike
+License:: LGPL, GNU Lesser General Public License
+
+Ramp is a library of extensions to Ruby and Rails base classes, including ActiveRecord, Array, Date, Enumerable, Hash, Kernel, Numeric, Object, Process, String, Time, and YAML. 
+
+Testing: 
+<ul>
+<li>Each has an associated test class, e.g., ArrayTest, DateTest, etc.
+<li>The easy way to run the tests: gem install ramp --test
+<li>Some of the ActiveRecord extensions use sqlite for testing. We don't install sqlite automatically because it requires some native extensions. If you need sqlite: gem install sqlite3-ruby
+</ul>
+
+
+== ActiveRecord
+
+* create_or_update_by: create a record, or update a record if value passed matches a field (or fields) in the AR object; includes method_missing function to make code more readable. 
+* seed: syntactic sugar alias for #create_or_update_by
+
+
+== ActiveRecord::ConnectionAdapters::SchemaStatements
+
+* add_column_and_index: database migration helper to add a table column and index at the same time.
+* remove_column_and_index: database migration helper to add a table column and index at the same time.
+
+
+== ActiveRecord::SaveExtensions
+
+* save_false_then_reload!: a transaction to save and reload a record, to help repair associations
+
+
+== Array
+
+* car, cdr: aka first, rest (see shifted)
+* choice, choices: one or more random elements from an array
+* cross: return the cross pairings of an array with another array
+* divvy: divides an array, like a pie, into a specified number of slices
+* join: same as Array#join with some improvments
+* onto: return a hash that maps an array's keys on to another array's values
+* rotate: moves the first element of an array to the end
+* rest: return the rest of the items of the array (aka cdr, aka shifted)
+* shifted, shifted!: return an array with the first n items shifted (aka cdr, aka rest)
+* shuffle, shuffle!: randomly sort an array efficiently; each of these methods are loaded only if needed (Ruby 1.8.7+ already defines shuffle)
+* slices: divide an array into specified number of equal size sub-arrays ([1,2,3,4,5,6]slices(3) => [[1,2],[3,4],[5,6]])
+* to_csv: join a multidimensional array into a string in CSV (Comma Separated Values), with each subarray becoming one 'line' in the output; typically for viewing in a spreadsheet such as Excel.
+* to_tdf: join a multidimensional array into a string in TDF (Tab Delimited Format); this is an alias for #to_tsv
+* to_tsv: join a multidimensional array into a string in TSV (Tab Separated Values), with each subarray becoming one 'line' in the output; typically for viewing in a spreadsheet such as Excel.
+* union: builds an array containing each of the unique elements of sub-arrays ([[1,2,3,4],[2,3,4,5],[3,4,5,6]].union => [1,2,3,4,5,6])
+
+
+== CSV
+
+* http_headers: provides web file download headers for text/csv content type and disposition.
+
+
+== Date
+
+* age_days, age_years
+* between: a random date between two specified dates
+* to_sql: date as a string formatted as expected for MySQL
+* weekday?, weekend?: is date a weekday or on the weekend
+
+
+== Enumerable
+
+* cartesian_product: return an array of all possible ordered tuples from arrays.
+* hash_by: convert the array to a hash by mapping each item to a key=>value pair.
+* index_by: convert the array to a hash by mapping each ite to a key=>item pair.
+* join: forwards to self.to_a.join
+* map_id: returns the id of an Enumerable object; *requires* that the object respond to an 'id' message
+* map_to_a, map_to_f, map_to_i, map_to_s, map_to_sym: convert each object to a specific type by calling its respective method to_a, to_i, to_f, to_s, to_sym
+* map_with_index: for each item, yield to a block with the item and its incrementing index
+* nitems_until, select_until: returns the number of, or an array containing, the leading elements for which block is false or nil.
+* nitems_while, select_while: returns the number of items, or an array containing the leading elements, for which block is not false or nil.
+* nitems_with_index, select_with_index: calls block with two arguments, the item and its index, for each item in enum. Returns the number of, or an array containing, the leading elements for which block is not false or nil. 
+* power_set: return an array with all subsets of the enum's elements
+
+
+== File
+
+* File.joindir: wrapper for File.join(File.dirname(...),string,...)
+
+
+== Hash
+
+* size?: return true if hash has any keys
+* each_sort: sort the keys then call each
+* each_key!: passes each key to a specified block and updates hash in place if the key changes
+* each_pair!: passes each key value pair to a specified block and updates the hash in place if the key or value change.
+* each_value!: passes each value to a specified block and updates the hash in place if the value changes.
+* map_pair: map each key-value pair by calling a a block
+* pivot: aggregates subtotals by keys and values, such as a rollup and rolldown 
+* to_yaml_sort: returns a YAML object, sorted by field name
+
+
+== Integer
+
+* maps: syntactic sugar to yield n times to a block, returning an array of any results (e.g. 3.maps{rand} => [0.4351325,0.7778625,0.158613534])
+
+
+== IO
+
+* readrow: reads a row line as with IO#readline, and return the row split it into fields 
+* IO.readrows: reads the entire file specified by name as individual row lines, and returns those rows split into fields, in an array of arrays.
+
+
+== Kernel
+
+* method_name: 
+* method_name_of_caller: returns the name of the method which called the current method, or the Nth parent up the call stack if the optional caller_index parameter is passed.
+
+
+== Math
+
+* ln(x): natural log of x
+* logn(x,b): log of x in base b
+
+
+== NilClass
+
+* blank?: return true (same as Rails)
+
+
+== Numeric
+
+* if: returns 0 if the passed flag is any of: nil, false, 0, [], {} and otherwise returns self
+* unless: returns 0 unless the passed flag is any of: nil, false, 0, [], {} and otherwise returns self
+* peta, tera, giga, mega, kilo, hecto, deka, deci, centi, milli, micro, nano: multiply/divide by powers of ten
+
+
+== Object
+
+* in?: returns boolean indicating whether the object is a member of the specified array parameter
+
+
+== Process
+
+Extensions that help debug Ruby programs.
+
+* (class) ps: output of the system 'ps' command, also including aliases, as raw plain text.
+* (class) pss: output of the system 'ps' command as a hash with each value set to the right type, e.g., integer, float, etc..
+
+
+== REXML::Attributes
+
+* hash: flattens the attributes hash set into a more useful ruby hash, e.g. {:height => 100, :width => 400 }
+
+
+== REXML::Document
+
+* remove_attributes: remove all the attributes from the document's elements
+
+
+== REXML::Element
+
+* remove_attributes: remove all the attributes from the element
+
+
+== String
+
+* capitalize_words (alias to titleize/titlecase): ensures the first character of each word is uppercase.
+* decrement: decrease the rightmost natural number, defaults to one value lower or by the optional step parameter value.
+* increment: increase the rightmost natural number, defaults to one value higher or by the optional step parameter value.
+* lorem: return a short random string, good for use in "lorem ipsum" sample text.
+* lowcase: translate a string to lowercase, digits and single underscores (e.g. to a method name)
+* prev/pred: previous string ("b" => "a", "bbc" => "bbb", "a" => "z", "880" => "879")
+* prev!/pred!: updates variable to the previous string in place (astring = "bbc", astring.prev!, puts astring => "bbb")
+* (class) prev_char/pred_char: returns the previous character, with a changed flag and carry flag; that is, there are three returned values, a string and two booleans.
+* split_tab: split the string into an array at each embedded tab ("Last\tFirst\tMiddle" => ["last","first","middle"])
+* split_tsv: split the string into an array at each embedded newline and embedded tab ("A\tB\t\C\nD\tE\tF" => [["A","B","C"],["D","E","F"]])
+* to_class: the global class reference of a given string
+* words: split the string into an array of words
+
+
+== Symbol
+
+* <=> and include the comparable mixin to compare symbols as strings
+
+
+== Time
+
+* (class) stamp: current time in UTC as a timestamp string ("YYYYMMDDHHMMSS")
+* to_sql: time as a string formatted as expected for MySQL
+
+
+== XML
+
+* (class) load_dir: specify a one or more directory patterns and pass each XML file in the matching directories to a block; see [Dir#glob](http://www.ruby-doc.org/core/classes/Dir.html#M002347) for pattern details.
+* (class) strip_all: delete exraneous junk from an XML text string, typically for sanitizing input
+* (class) strip_attributes: delete all attributes from an XML text string
+* (class) strip_comments: delete all comments from an XML text string
+* (class) strip_microsoft: delete all proprietary Microsoft code from an XML text string
+* (class) strip_unprintables: delete all unprintable characters from an XML text string
+
+
+== YAML
+
+* (class) load_dir: specify a one or more directory patterns and pass each YAML file in the matching directories to a block; see [Dir#glob](http://www.ruby-doc.org/core/classes/Dir.html#M002347) for pattern details.
+
+
+== Changes
+
+- 1.7.2 Genmcutter update
+- 1.7.1.8 Add Enumerable#map_with_index
+- 1.7.1.6 Add ActiveRecord::SaveExtensions#save_false_then_reload!
+- 1.7.1.3 Add XML#strip_xxx 
+- 1.7.1.2 Update gems: Gemcutter, Ruby 1.9.1, JRuby sqlite3
+- 1.7.1.0 Add XML attributes methods #
+- 1.7.0.9 Add Enumerable #hash_by, #index_by
+- 1.7.0.7 Add Array#to_tsv, String#split_tsv, improve Array#to_csv
+- 1.7.0.6 Add Array#shuffle, Array#shuffle! 
+- 1.7.0.5 Add Array#shifted, Array#rest, Array#car, Array#cdr
+- 1.7.0.4 Upgrade IO#readrows and #readrow to use options
+- 1.7.0.2 Add Array#to_tdf
+- 1.7.0.1 Remove sqlite3 testing dependency
+- 1.6.9.6 Add Symbol with comparable and <=>
+- 1.6.9.5 Add ActiveRecord testing with sqlite3
+- 1.6.9.4 JRuby install and test successful
+- 1.6.9.3 Array#join add infix, prefix, suffix
+- 1.6.9.2 Improve ri docs
+- 1.6.9.1 Add Array#onto, Enumerable#intersect?
+- 1.6.9.0 Add IO, File, ActiveRecord#seed
+- 1.6.8.9 Add Enumerable#to_h, Array#hash, Hash#each_key!, Hash#each_pair, Hash#each_value!
+- 1.6.8.8 Add Hash#map_pair, Hash#size?, Hash#pivot
+- 1.6.8.7 Add Math
+- 1.6.8.6 Add ActiveRecord SchemaStatements
+- 1.6.8.5 Add Integer#maps, String#ACCENTS
+- 1.6.8.4 Add XML
+- 1.6.8.3 Add ActiveRecord
+- 1.6.8.2 Add String#lowcase
+- 1.6.8 Add map_to_xxx methods
+- 1.6.7 Add CSV
+- 1.6.6 Add Array#to_csv, Integer, String#lorem, etc., improve tests
+- 1.6.4 Bug fixes: String characters and YAML test files
+- 1.6.2 Improve organizaiton of class files to lib/ramp
+- 1.6.0 Upgraded to work with Ruby 1.9.1
+- 1.5.0 Combined all Ruby extension files into one gem
+- 1.0.0 Original 
+
+=end
+
+%w{active_record active_record/save_extensions array csv date enumerable file hash integer io kernel math nil numeric object process string symbol time xml yaml}.map{|x|
+  require File.dirname(__FILE__) + "/webget_ruby_ramp/#{x}.rb"
+}
+

data/lib/webget_ruby_ramp/active_record.rb

@@ -0,0 +1,119 @@
+require 'activerecord'
+require 'active_record'
+
+#:startdoc:
+# ActiveRecord extensions
+
+module ActiveRecord #:doc:
+
+class Base #:doc:
+
+  # Create a record, or update a record if value passed matches a field in the AR object;
+  # includes method_missing function to make code more readable
+  #
+  # Most common use will be for testing (fixture/mock object generation)
+  #
+  # Three versions of method included:
+  # create_or_update
+  # create_or_update_by
+  # create_or_update_by_xxx (where xxx is a field name)
+  #
+  # Inspired by http://www.intridea.com/2008/2/19/activerecord-base-create_or_update-on-steroids-2
+  #
+  # ==Example
+  # { "admin"     => ["Administrator", 1000], 
+  #   "member"    => ["Member", 1], 
+  #   "moderator" => ["Moderator", 100],
+  #   "disabled"  => ["Disabled User", -1] }.each_pair do |key, val|
+  #     Role.create_or_update_by_key(:key => key, :name => val[0], :value => val[1])
+  # end
+
+  def self.create_or_update(options = {})
+    self.create_or_update_by(:id, options)
+  end
+
+
+  # Create or update a record by field (or fields).
+  # This will look for each field name as a key in the options hash.
+  #
+  # ==Example
+  #   attributes={:name="John Smith", :email=>"john@example.com", :birthdate=>'1980/01/01'}
+  #   User.create_or_update_by(:email,attributes)
+  #   => if a user with that email exists then update his name and birthdate, else create him
+  #
+  # ==Example with multiple conditions
+  #   attributes={:name="John Smith", :email=>"john@example.com", :birthdate=>'1980/01/01'}
+  #   User.create_or_update_by([:name,:birthdate],attributes)
+  #   => if a user with that name and birthdate exists then update his email, else create him
+  #
+  # The fields can be any mix of symbols or strings.
+  # The option keys can be any mix of symbols or strings.
+
+  def self.create_or_update_by(condition_keys, attribute_pairs = {})
+    condition_pairs=[*condition_keys].map{|key| [key,(attribute_pairs.delete(key)||attribute_pairs.delete(key.to_s)||attribute_pairs.delete(key.to_sym))]}.to_h
+    record = find(:first, :conditions => condition_pairs) || self.new
+    if record.new_record? then attribute_pairs.merge!(condition_pairs) end
+    attribute_pairs.each_pair{|key,val| record.send key.to_s+'=', val}
+    record.save!
+    return record
+  end
+
+
+  # Set up a database with initial data, e.g. in rake db:seed method.
+  #
+  # This will look for each field name as a key in the options hash.
+  #
+  # This method calls #create_or_update_by (and you may want to change
+  # this behavior to do more, e.g. to test that a DB and table exists).
+  #
+  # ==Example
+  #   attributes={:name="John Smith", :email=>"john@example.com", :birthdate=>'1980/01/01'}
+  #   User.create_or_update_by(:email,attributes)
+  #   => if a user with that email exists then update his name and birthdate, else create him
+  #
+  # ==Example with multiple conditions
+  #   attributes={:name="John Smith", :email=>"john@example.com", :birthdate=>'1980/01/01'}
+  #   User.create_or_update_by([:name,:birthdate],attributes)
+  #   => if a user with that name and birthdate exists then update his email, else create him
+  #
+  # The fields can be any mix of symbols or strings.
+  # The option keys can be any mix of symbols or strings.
+
+  def self.seed(condition_keys, attribute_pairs = {})
+    self.create_or_update_by(condition_keys, attribute_pairs)
+  end
+
+
+  # Method missing for create_or_update_by_xxx that forwards to #create_or_update_by
+  #
+  # ==Example
+  #   MyModel.create_or_update_by_foo(options)
+  #   => MyModel.create_or_update_by(:foo,option)
+
+  def self.method_missing_with_create_or_update(method_name, *args) 
+    if match = method_name.to_s.match(/create_or_update_by_([a-z0-9_]+)/)  
+      field = match[1]
+      return create_or_update_by(field,*args)
+    end
+    return method_missing_without_create_or_update(method_name, *args)
+  end
+
+
+  # For alias method chain
+  def self.included(base)
+    # base == ActiveRecord::Base (the class)
+    base.class_eval do
+        # class_eval makes self == ActiveRecord::Base, and makes def define instance methods.
+        extend ClassMethods
+        # If has_many were an instance method, we could do this
+        #   alias_method_chain :has_many, :association_option; end            
+        # but it's a class method, so we have to do the alias_method_chain on  
+        # the meta-class for ActiveRecord::Base, which is what class << self does.   
+        class << self;  alias_method_chain :method_missing, :create_or_update;  end
+      end
+  end
+
+
+end
+
+end

data/lib/webget_ruby_ramp/active_record/connection_adapters/abstract/schema_statements.rb

@@ -0,0 +1,24 @@
+module ActiveRecord
+  module ConnectionAdapters 
+    module SchemaStatements
+
+      # Add a column and its index.
+      # This just calls #add_column then #add_index
+
+      def add_column_and_index(table_name, column_name, type, options = {})
+        add_column(table_name, column_name, type, options)
+        add_index(table_name, column_name, type, options)
+      end
+
+
+      # Remove a column and its index in one step.
+      # This just calls #remove_column then #remove_index.
+
+      def remove_column_and_index(table_name, column_name, type, options = {})
+        remove_column(table_name, column_name, type, options)
+        remove_index(table_name, column_name, type, options)
+      end
+
+    end
+  end
+end

data/lib/webget_ruby_ramp/active_record/save_extensions.rb

@@ -0,0 +1,35 @@
+module ActiveRecord::SaveExtensions
+
+  # Save the record without validation, then reload it.
+  # If the record is valid then return true, otherwise raise RecordInvalid.
+  # This solves an issue we found with Rails associations not saving.
+  #
+  # By Andrew Carpenter (acarpen@wested.org)
+  #
+  # Deprecated, superceded by #save_redux!
+
+  def save_false_then_reload!
+    transaction do
+      save(false)
+      reload
+      valid? or raise ActiveRecord::RecordInvalid.new(self)
+    end
+    return true
+  end
+
+
+  # Save the record without validation, then reload, then save with validtion.
+  # This ensure that rails brings back the correct associations to validate.
+  # This solves an issue we found with Rails associations not saving.
+
+  def save_redux!
+    transaction do
+      save(false)
+      reload
+      save!
+    end
+    return true
+  end
+
+end
+ActiveRecord::Base.send(:include, ActiveRecord::SaveExtensions)

data/lib/webget_ruby_ramp/array.rb

@@ -0,0 +1,370 @@
+require 'csv'
+ 
+# Array extensions
+
+class Array
+
+
+  # Alias join because we're going to override it
+
+  alias :ruby_join :join
+
+
+  # Concatenate the items into a string by join.
+  #
+  # ==Typical Array#join with infix
+  #   list=['a','b','c']
+  #   list.join("*") => "a*b*c"
+  #
+  # ==Improved join with infix, prefix, suffix
+  #   list=['a','b','c']
+  #   list.join("*","[","]") => "[a]*[b]*[c]"
+  #
+  # ==Improved join with just prefix and suffix
+  #   list=['a','b','c']
+  #   list.join("[","]") => "[a][b][c]"
+
+  def join(*fixes)
+    if fixes.is_a?(String) then return self.ruby_join(fixes) end
+    case fixes.size
+    when 0
+      return self.ruby_join()
+    when 1
+      return self.ruby_join(fixes[0])
+    when 2
+      prefix=fixes[0].to_s
+      suffix=fixes[1].to_s
+      return self.map{|s| prefix + s.to_s + suffix}.ruby_join()
+    when 3
+      infix =fixes[0].to_s
+      prefix=fixes[1].to_s
+      suffix=fixes[2].to_s
+      return map{|s| prefix + s.to_s + suffix}.ruby_join(infix)
+    else
+      raise "join(fixes[#{fixes.size}]"
+    end
+  end
+
+
+  # Return true if size > 0
+  #
+  # ==Examples
+  #   [1,2,3].size? => true
+  #   [].size? => false
+
+  def size?
+    return size>0
+  end
+
+
+  # Move the first item to the last by using Array#shift and Array#push
+  #
+  # ==Examples
+  #   [1,2,3,4].rotate! => [2,3,4,1]
+  #   ['a','b','c'].rotate! => ['b','c','a']
+  #
+  # Return self
+  
+  def rotate!
+    push item=shift
+    self
+  end
+
+  
+  # Return a random item from the array
+  #
+  # ==Examples
+  #   [1,2,3,4].choice => 2
+  #   [1,2,3,4].choice => 4
+  #   [1,2,3,4].choice => 3
+  #
+  # Implemented in Ruby 1.9
+  
+  def choice
+    self[Kernel.rand(size)]
+  end
+
+
+  # Return a new array filled with _count_ calls to choice
+  #
+  # ==Examples
+  #   [1,2,3,4].choices(2) => [3,1]
+  #   [1,2,3,4].choices(3) => [4,2,3]
+  
+  def choices(count)
+    arr = Array.new
+    count.times { arr << self.choice }
+    return arr
+  end
+
+
+  # Return a hash of this array's items as keys
+  # mapped onto another array's items as values.
+  #
+  # ==Example
+  #   foo=[:a,:b,:c]
+  #   goo=[:x,:y,:z]
+  #   foo.onto(goo) => {:a=>:x, :b=>:y, :c=>:z}
+  #
+  # This is identical to calling foo.zip(values).to_h
+
+  def onto(values)
+    zip(values).to_h
+  end
+
+
+  ##############################################################
+  # 
+  # GROUPINGS
+  #
+  ##############################################################
+
+
+  # Return items in groups of _n_ items (aka slices)
+  #
+  # ==Examples
+  #   [1,2,3,4,5,6,7,8].slices(2) => [[1,2],[3,4],[5,6],[7,8]]
+  #   [1,2,3,4,5,6,7,8].slices(4) => [[1,2,3,4],[5,6,7,8]]
+  #
+  # If the slices don't divide evenly, then the last is smaller.
+  #
+  # ==Examples
+  #   [1,2,3,4,5,6,7,8].slices(3) => [[1,2,3],[4,5,6],[7,8]] 
+  #   [1,2,3,4,5,6,7,8].slices(5) => [[1,2,3,4,5],[6,7,8]] 
+
+  def slices(slice_length)
+    arr=[]
+    i=0
+    while i<length
+      arr.push self[i...(i+slice_length)]
+      i+=slice_length
+    end
+    return arr
+  end
+
+
+  # Divvy the array, like a pie, into _n_ number of slices.
+  #
+  # If the array divides evenly, then each slice has size/n items.
+  #
+  # Otherwise, divvy makes a best attempt by rounding up to give
+  # earlier slices one more item, which makes the last slice smaller:
+  #
+  # ==Examples
+  #   [1,2,3,4,5].divvy(2) => [[1,2,3],[4,5]]
+  #   [1,2,3,4,5,6,7].divvy(3) => [[1,2,3],[4,5,6],[7]]
+  #
+  # If the array size so small compared to _n_ that there is
+  # no mathematical way to _n_ slices, then divvy will return
+  # as many slices as it can.
+  #
+  # ==Examples
+  #   [1,2,3,4,5,6].divvy(4) => [[1,2],[3,4],[5,6]]
+
+  def divvy(number_of_slices)
+    return slices((length.to_f/number_of_slices.to_f).ceil)
+  end
+
+
+  ##############################################################
+  # 
+  # COMBINATIONS
+  #
+  ##############################################################
+
+  
+  # Return the union of the array's items.
+  # In typical use, each item is an array.
+  #
+  # ==Example using Ruby Array pipe
+  #   a=[1,2,3]
+  #   b=[2,3,4]
+  #   a | b => [1,2,3,4]
+  #
+  # ==Example using union method
+  #   arr=[a,b]
+  #   => [1,2,3,4]
+  #
+  # This is identical to 
+  
+  # ==Examples with proc
+  #   arr.map(&:foo).union
+  #   => foos that are in any of the array items
+
+  def union
+    inject{|inj,item| inj | item.to_a }
+  end
+
+
+  # Return the intersection of the array's items.
+  # In typical usage, each item is an array.
+  #
+  # ==Examples
+  #   arr=[[1,2,3,4],[2,3,4,5],[3,4,5,6]]
+  #   arr.intersect
+  #   => [3,4]
+  #
+  # ==Examples with proc
+  #   arr.map(&:foo).intersect
+  #   => foos that are in all of the array items
+
+  def intersect
+    inject{|inj,item| inj & item.to_a }
+  end
+
+  
+
+  ##############################################################
+  # 
+  # LIST PROCESSING
+  #
+  ##############################################################
+
+  # Returns the rest of the items of self, after a shift.
+  #
+  # ==Example
+  #   list=['a','b','c']
+  #   list.shift => 'a'
+  #   list.shifted => ['b','c']
+  #
+  # ==Example with length
+  #   list.shifted(0) => ['a','b','c']
+  #   list.shifted(1) => ['b','c']
+  #   list.shifted(2) => ['c']
+  #   list.shifted(3) => []
+  #
+  # Ruby programmers may prefer this alias wording:
+  #   list.first => 'a'
+  #   list.rest => ['b','c']
+  #
+  # LISP programmers may prefer this alias wording:
+  #   list.car => 'a'
+  #   list.cdr => ['b','c']
+  #
+
+  def shifted(number_of_items=1)
+   slice(n,self.length-number_of_items)
+  end
+
+  alias :car :first
+  alias :cdr :shifted
+  alias :rest :shifted
+
+
+  # Delete the first _number_of_items_ items. Returns the array, not the deleted items.
+  # 
+  # ==Example
+  #   list=['a','b','c']
+  #   list.shifted!
+  #   list => ['b','c']
+  #
+  # ==Example with length:
+  #   list=['a','b','c']
+  #   list.shifted!(2)
+  #   list => ['c']
+  #
+  # If _n_ is greater than the array size, then return []
+
+  def shifted!(number_of_items=1)
+   slice!(0,number_of_items)
+   return self
+  end
+
+  alias :cdr! :shifted!
+  alias :rest! :shifted!
+
+
+  # Randomly arrange the array items.
+  #
+  # This implementation is optimized for speed, not for memory use.
+  # See http://codeidol.com/other/rubyckbk/Arrays/Shuffling-an-Array/
+  #
+  # This method definition is skipped if Array#shuffle! is already defined.
+  #
+  # ==Example
+  #   list=
+  #   list=['a','b','c']
+  #   list.shuffle!
+  #   list => ['c','a','b']
+
+  if !instance_methods.include?('shuffle!')
+    def shuffle!  
+      each_index do |i| 
+        j = rand(length-i) + i
+        self[j], self[i] = self[i], self[j]  
+      end
+    end
+  end
+
+  # Return the array items in random order.
+  #
+  # This implementation is optimized for speed, not for memory use.
+  # See http://codeidol.com/other/rubyckbk/Arrays/Shuffling-an-Array/
+  #
+  # This method definition is skipped if Array#shuffle is already defined.
+  # For example, Ruby 1.8.7 Array#shuffle is already defined.
+  #
+  # ==Example
+  #   list=
+  #   list=['a','b','c']
+  #   list.shuffle!
+  #   list => ['c','a','b']
+
+  if !instance_methods.include?('shuffle') and instance_methods.include?('shuffle!')
+    def shuffle  
+      dup.shuffle!  
+    end
+  end
+
+
+  ##############################################################
+  # 
+  # CASTS
+  #
+  ##############################################################
+
+  # Returns a CSV (Comma Separated Value) string of this array.
+  #
+  # ==Example of a one-dimensional array
+  #
+  #   [1,2,3].to_csv => "1,2,3\n"
+  #
+  # ==Example of a multi-dimensional array
+  #
+  #   [[1,2,3],[4,5,6]] => "1,2,3\n4,5,6\n"
+  #
+  # N.b. this method uses the multi-dimensional if the
+  # array's first item is also an array.
+
+  def to_csv(ops={})
+
+    generator = RUBY_VERSION >= "1.9" ? CSV : CSV::Writer
+
+    str=''
+    if size>0 and self[0].is_a?Array
+      generator.generate(str) do |csv|
+        self.each do |row|
+          csv << row
+        end
+      end
+    else
+      generator.generate(str) do |csv|
+        csv << self.map{|item| item.to_s}
+      end
+    end
+    return str
+  end
+
+
+  # Returns a TSV (Tab Separated Value) string
+  # representation of a multi-dimensional array.
+  #
+  # Each subarray becomes one 'line' in the output.
+
+  def to_tsv(ops={})
+    self.map{|row| row.join("\t")+"\n"}.join
+  end
+
+  alias to_tdf to_tsv
+
+end