webget_ruby_ramp 1.8.0 → 1.8.2

data/lib/webget_ruby_ramp/integer.rb

@@ -6,16 +6,17 @@ class Integer
 
   # Syntactic sugar to yield n times to a block.
   #
-  # Return an array of any results.
-  #
-  # ==Example
-  #   3.maps{rand} => [0.0248131784304143, 0.814666170190905, 0.15812816258206]
-  #
-  # ==Parallel to Integer#times
-  #
+  # 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}

data/lib/webget_ruby_ramp/io.rb

@@ -8,55 +8,59 @@ 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.
   #
-  # ==Example
+  # @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"]]
   #
-  # ==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"
+  # @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)
+  # @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:
+  # @see
   # - File#readline
   # - File#readlines
   # - File#readrow
 
-  def IO.readrows(name, options={})
+  def IO.readrows(filename, options={})
     row_sep||=options[:row]||$/||"\n"
     col_sep||=options[:col]||$;||"\t"
-    return IO.readlines(name, row_sep).map{|line| line.chomp(row_sep).split(col_sep)}
+    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.
   #
-  # ==Example
+  # 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"]]
   #
-  # ==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)
+  # @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"] 
   #
-  # Note: the col option is sent along to String#split, so can be a string or a regexp.
-  #
-  # See:
-  # - File#readline
-  # - File#readlines
-  # - File#readrows
+  # @see File#readline
+  # @see File#readlines
+  # @see File#readrows
 
   def readrow(options={})
     row_sep||=options[:row]||$/||"\n"

data/lib/webget_ruby_ramp/kernel.rb

@@ -14,6 +14,18 @@ module Kernel
   #-
   # 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
@@ -27,6 +39,20 @@ module Kernel
   #-
   # 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
@@ -38,6 +64,12 @@ module Kernel
   # 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  

data/lib/webget_ruby_ramp/math.rb

@@ -5,14 +5,22 @@
 module Math
 
 
-  # Return the natural log of _num_
+  # @return [Float] the natural log of _num_
+  #
+  # @example
+  #   Math.ln(2.719)
+  #   => 1.00
 
   def Math.ln(num)
    Math.log(num)
   end
 
 
-  # Return the log of _num_ in base _base_
+  # @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)

data/lib/webget_ruby_ramp/nil.rb

@@ -5,12 +5,15 @@
 
 class NilClass
 
- # Same as Rails
+ # @return [true]
+ 
  def blank?
   return true
  end
 
- # Return false
+
+ # @return [false]
+
  def size?
   return false
  end

data/lib/webget_ruby_ramp/numeric.rb

@@ -4,9 +4,10 @@
 
 class Numeric
 
- # Return 0 if the given flag is any of: nil, false, 0, [], {}
+
+ # @return 0 if the given flag is any of: nil, false, 0, [], {}
  #
- # ==Example
+ # @example
  #   3.if(true) => 3
  #   3.if(false) => 0
  #   
@@ -16,9 +17,9 @@ class Numeric
  end
 
 
- # Return self if flag is nil, false, 0, [], {}; otherwise return 0.
+ # @return self if flag is nil, false, 0, [], {}; otherwise return 0.
  #
- # ==Example
+ # @example
  #   3.unless(true) => 0
  #   3.unless(false) => 3
 
@@ -27,71 +28,4 @@ class Numeric
  end
 
 
- ###
- #
- #  Metric conversions
- #
- ###
-
- # Return self / 10^15
- def peta
-  self/1000000000000000
- end
-
- # Return self / 10^12
- def tera
-  self/1000000000000
- end
-
- # Return self / 10^9
- def giga
-  self/1000000000
- end
-
- # Return self / 10^6
- def mega
-  self/1000000
- end
-
- # Return self / 10^3
- def kilo
-  self/1000
- end
-
- # Return self / 10^2
- def hecto
-  self/100
- end
-
- # Return self / 10
- def deka
-  self/10
- end
- 
- # Return self * 10
- def deci
-  self*10
- end
-
- # Return self * 10^2
- def centi
-  self*100
- end
-
- # Return self * 10^3
- def milli
-  self*1000
- end
-
- # Return self * 10^6
- def micro
-  self*1000000
- end
-
- # Return self * 10^9
- def nano
-  self*1000000000
- end
-
-
 end

data/lib/webget_ruby_ramp/object.rb

@@ -6,15 +6,16 @@ class Object
 
   # Syntactic sugar for arrays.
   #
-  # ==Definition
+  # Definition:
   #   object.in? array === array.include? object
   #
-  # ==Example
+  # @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

data/lib/webget_ruby_ramp/process.rb

@@ -23,6 +23,13 @@ module Process
   # Get the 'ps' command as one long text string.
   #
   # This is typically useful for logging to a text file.
+  #
+  # @example
+  #   pid = 100
+  #   Process.ps(pid)
+  #   => "0.0 bfd86194 21:14:51 ..."
+  #
+  # @return [String] lots of data about the process
 
   def self.ps(pid=Process.pid)
     `#{self.ps_command} #{pid.to_i}`
@@ -30,6 +37,13 @@ module Process
 
 
   # Get the 'ps' command as a hash of keys and values.
+  #
+  # @return [Hash<String,String>] the ps command options as keys and values
+  #
+  # @example
+  #   pid = 100
+  #   Process.pss(pid)
+  #   => {"cp"=>0.0, "esp"=>"bfd86194", "etime"=>"21:14:51", ...  }
   # -
   # OPTIMIZE: add dates, times
 
@@ -60,9 +74,16 @@ module Process
     return h
   end
 
+
   # Get the list of process alias keywords as typically defined by the shell.
   #
   # For example, a shell may consider "%cpu" and "pcpu" to be identical.
+  #
+  # @example
+  #   Process::PS_ALIASES_DEFAULT
+  #   => {"%cpu"=>"pcpu", "sigmask"=>"blocked", "cls"=>"policy", ... }
+  #
+  # @return [Hash<String,String>] process keyword aliases
 
   PS_ALIASES_DEFAULT={
     '%cpu'=>'pcpu',
@@ -106,6 +127,12 @@ module Process
   # Get the list of process alias keywords as typically defined by the shell.
   #
   # For example, a shell may consider "%cpu" and "pcpu" to be identical.
+  #
+  # @example                                                                          
+  #   Process.ps_aliases
+  #   => {"%cpu"=>"pcpu", "sigmask"=>"blocked", "cls"=>"policy", ... }                                   
+  #                                                                                                                
+  # @return [Hash<String,String>] process keyword aliases 
 
   def self.ps_aliases
     @@ps_aliases||=PS_ALIASES_DEFAULT
@@ -115,6 +142,13 @@ module Process
   # Set the list of process alias keywords.
   #
   # For example, a shell may consider "%cpu" and "pcpu" to be identical.
+  #
+  # @example                                                                          
+  #   Process::ps_aliases={ {"%cpu"=>"pcpu", "sigmask"=>"blocked", "cls"=>"policy" }
+  #   => {"%cpu"=>"pcpu", "sigmask"=>"blocked", "cls"=>"policy"}     
+  #        
+  # @param [Hash<String,String>] aliases                                 
+  # @return [Hash<String,String>] aliases
 
   def self.ps_aliases=(aliases)
     @@ps_aliases=aliases
@@ -128,8 +162,12 @@ module Process
 
   # Get the list of process keywords.
   #
-  # ==Example
-  #   Process.ps_keys => ["blocked","group","pending","size"]
+  # @example
+  #   Process.ps_keys
+  #   => ["blocked","group","pending","size"]
+  #
+  # @return [Array<String>] the list of process keywords.
+
 
   def self.ps_keys
     @@ps_keys||=PS_KEYS_DEFAULT
@@ -138,8 +176,11 @@ module Process
  
   # Set the list of process keywords.
   #
-  # ==Example 
+  # @example 
   #   Process.ps_keys = ["blocked","group","pending","size"]
+  #
+  # @param [Array<String>] keywords
+  # @return [Array<String>] keywords
 
   def self.ps_keys=(keys)
     @@ps_keys=keys
@@ -153,8 +194,11 @@ module Process
 
   # Get the process command, i.e. what the sytem will call for the "ps" command.
   #
-  # ==Example
-  #   Process.ps_command => "ps h ww -o blocked,group,pending,size"
+  # @example
+  #   Process.ps_command
+  #   => "ps h ww -o blocked,group,pending,size"
+  #
+  # @return [String] the process command
  
   def self.ps_command
     @@ps_command||=PS_COMMAND_DEFAULT
@@ -163,9 +207,12 @@ module Process
 
   # Set the process command, i.e. what the sytem will call for the "ps" command.
   #
-  # ==Example
+  # @example
   #   Process.ps_command = "ps h ww -o blocked,group,pending,size"
- 
+  #
+  # @param [String] the process command
+  # @return [String] the process command 
+
   def self.ps_command=(command)
     @@ps_command=command
   end

data/lib/webget_ruby_ramp/string.rb

@@ -4,44 +4,56 @@
 
 class String
 
-  ACCENTS =  Hash[*'à a á a â a ã a ä a å a ā a ă a æ ae ď d đ d ç c ć c č c ĉ c ċ c è e é e ê e ë e ē e ę e ě e ĕ e ė e ƒ f ĝ g ğ g ġ g ģ g ĥ h ħ h ì i ì i í i î i ï i ī i ĩ i ĭ i į j ı j ij j ĵ j ķ k ĸ k ł l ľ l ĺ l ļ l ŀ l
- ñ n ń n ň n ņ n ʼn n ŋ n ò o ó o ô o õ o ö o ø o ō o ő o ŏ o ŏ o œ oek ą q ŕ r ř r ŗ r ś s š s ş s ŝ s ș s ť t ţ t ŧ t ț t ù u ú u û u ü u ū u ů u ű u ŭ u ũ u ų u ŵ w ý y ÿ y ŷ y ž z ż z ź z'.split]
 
-
- # Return the string with words capitalized
+ # @return [String] self, with words capitalized
+ # @example 
+ #   "foo goo hoo".capitalize_words
+ #    => "Foo Goo Hoo"
 
  def capitalize_words
   split(/\b/).map{|word| word.capitalize }.join
  end
 
 
- # Return an array that is the string split into words, i.e. split(\W*\b\*)
+ # @return [Array<String>] an array that is the string split into words, i.e. split(\W*\b\*)
+ # @example
+ #   "foo goo hoo".words
+ #   => ["foo", "goo", "hoo"]
 
  def words
   split(/\W*\b\W*/)
  end
 
 
- # Return an array that is the string split at tabs, i.e. split(/\t/)
+ # @return [Array<String>] an array that is the string split at tabs, i.e. split(/\t/)
+ # @example
+ #   "foo\tgoo\thoo".split_tab
+ #   => ["foo", "goo", "hoo"]
 
  def split_tab
   split(/\t/)
  end
 
 
- # Return an array that is the string split at newlines, then tabs.
  # This is useful to split a TSV (Tab Separated Values) string
  # into an array of rows, and each row into an array of fields.
+ #
+ # @return [Array<String>] an array that is the string split at newlines, then tabs.
+ #
+ # @example
+ #   "foo\tgoo\thoo\n"ioo\tjoo\tkoo\nloo\tmoo\tnoo".split_tsv
+ #   => [["foo", "goo", "hoo"], ["ioo", "joo", "koo"], ["loo", "moo", "noo"]]
 
  def split_tsv
    split(/\n/).map{|line| line.split(/\t/)}
  end
 
 
- # Return the string in lowercase, with any non-word-characters
- # replaced with single underscores (aka low dashes).
+ # @return [String] self in lowercase,
+ #    with any non-word-characters
+ #    replaced with single underscores (aka low dashes).
  #
- # ==Example
+ # @example
  #   'Foo Goo Hoo' => 'foo_goo_hoo'
  #   'Foo***Goo***Hoo' => 'foo_goo_hoo'
 
@@ -50,9 +62,9 @@ class String
  end
 
 
- # Return the string as an XML id, which is the same as #lowcase
+ # @return [String] the string as an XML id, which is the same as #lowcase
  #
- # ==Example
+ # @example
  #   "Foo Hoo Goo" => 'foo_goo_hoo'
  #   "Foo***Goo***Hoo" => 'foo_goo_hoo'
 
@@ -63,6 +75,8 @@ class String
  # Ruby String#to_class method to convert from a String to a class
  #
  # From Mirage at http://infovore.org/archives/2006/08/02/getting-a-class-object-in-ruby-from-a-string-containing-that-classes-name/
+ #
+ # @return [Class] the string converted to a class 
 
  def to_class
   split('::').inject(Kernel) {|scope, const_name| scope.const_get(const_name)}
@@ -71,12 +85,14 @@ class String
 
  # Increment the rightmost natural number 
  #
- # ==Example
+ # @return [String] the string with an incremented rightmost number
+ #
+ # @example
  #   'foo5bar'.increment => 'foo4bar'
  #   'foo5bar'.increment(3) => 'foo8bar'
  #   'foo9bar'.increment => 'foo10bar'
  #
- # - see String#decrement
+ # @see String#decrement
 
  def increment(step=1)
   self=~/\d+/ ? $`+($&.to_i+step).to_s+$' : self
@@ -85,21 +101,23 @@ class String
 
  # Decrement the rightmost natural number
  # 
- # ==Example
+ # @return [String] the string with a decremented rightmost number
+ #
+ # @example
  #   'foo5bar'.decrement => 'foo4bar'
  #   'foo5bar'.decrement(3) => 'foo2bar'
  #   'foo10bar'.derement => 'foo9bar'
  #
- # - see String#increment
+ # @see String#increment
 
  def decrement(step=1)
   self=~/\d+/ ? $`+($&.to_i-step).to_s+$' : self
  end
 
 
- # Return the previous character, with a changed flag and carry flag
+ # @return [String] the previous character, with a changed flag and carry flag
  #
- # ==Examples
+ # @example
  #   String.prev_char('n') => 'm', true, false   # change 
  #   String.prev_char('a') => 'z', true, true    # change & carry
  #   String.prev_char('6') => '5', true, false   # change
@@ -122,16 +140,16 @@ class String
   end
  end
 
- # Return the previous string
+ # @return [String] the previous string
  #
- #  c.f. String#next
+ # @see String#next
  #
- # ==Examples
+ # @example
  #   '888'.prev => '887'
  #   'n'.prev => 'm'
  #   'N'.prev => 'M'
  #
- # ==Examples with carry
+ # @example with carry
  #   '880'.prev => '879'
  #   'nna'.prev => 'nmz'
  #   'NNA'.prev => 'NMZ'
@@ -143,6 +161,8 @@ class String
 
 
  # Do String#prev in place
+ #
+ # @return [String] self
 
  def prev!
   return self if length==0
@@ -156,6 +176,7 @@ class String
    index-=1
    return nil if index<0
   end
+  return self
  end
 
  alias pred  prev   # String#pred : predecessor :: String#succ : successor
@@ -177,15 +198,24 @@ class String
  #
  ##
  
- # Return a random length suitable for a "lorem ipsum" string.
+ # @return [Integer[ a random length suitable for a "lorem ipsum" string.
  #
  # This method uses 1+rand(10)
+ #
+ # @example
+ #    String.lorem_length => 3
+ #    String.lorem_length => 9
+ #    String.lorem_length => 5
 
  def self.lorem_length
   1+rand(10)
  end
 
- # Return a random string suitable for "lorem ipsum" text.
+ # @return [String] a random string suitable for "lorem ipsum" text.
+ #
+ # @example
+ #   String.lorem => "galkjadscals"
+ #   String.lorem(4) => "qtgf"
  #
  # This method chooses from lowercase letters a-z.
  #