blackwinter-ruby-nuggets 0.4.0

data/README

@@ -0,0 +1,60 @@
+= ruby-nuggets - Some extensions to the Ruby programming language
+
+== VERSION
+
+This documentation refers to ruby-nuggets version 0.4.0
+
+
+== DESCRIPTION
+
+ruby-nuggets provides a collection of extensions to Ruby core classes. In
+its effort, it's similar to projects like Facets[http://facets.rubyforge.org]
+and Extensions[http://extensions.rubyforge.org] (or even
+Labrador[http://rubyforge.org/projects/labrador/]), though not as ambitious ;-)
+This is simply where I put stuff that I need on a more or less regular basis
+or that struck me as interesting while surfing the web, reading books, or
+following discussions on ruby-talk.
+
+There are several ways to get at the nuggets you're interested in:
+
+  # The usual way: Just require() what you need
+  require 'nuggets/object/singleton_class'
+
+  # The more fancy way ;-) (see the documentation of Nuggets() for more examples)
+  require 'nuggets'
+  Nuggets(:object => 'singleton_class', :string => %w[nsub sub_with_md])
+
+  # Finally, get everything there is...
+  require 'nuggets/all'
+
+Please be aware that some of the things herein might not work as expected or
+cause other libraries to misbehave. Use at your own risk!
+
+
+== LINKS
+
+* <http://prometheus.rubyforge.org/ruby-nuggets>
+* <http://prometheus.rubyforge.org/svn/scratch/ruby-nuggets>
+* <http://github.com/blackwinter/ruby-nuggets>
+
+
+== AUTHORS
+
+* Jens Wille <mailto:jens.wille@uni-koeln.de>
+
+
+== LICENSE AND COPYRIGHT
+
+Copyright (C) 2007-2008 Jens Wille
+
+ruby-nuggets is free software: you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any later
+version.
+
+ruby-nuggets is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+ruby-nuggets. If not, see <http://www.gnu.org/licenses/>.

data/Rakefile

@@ -0,0 +1,20 @@
+begin
+  require 'hen'
+rescue LoadError
+  abort "Please install the 'hen' gem first."
+end
+
+require 'lib/nuggets/version'
+
+Hen.lay! {{
+  :rubyforge => {
+    :package => 'ruby-nuggets'
+  },
+
+  :gem => {
+    :version     => Nuggets::VERSION,
+    :summary     => 'Some extensions to the Ruby programming language.',
+    :files       => FileList['lib/**/*.rb'].to_a,
+    :extra_files => FileList['[A-Z]*'].to_a
+  }
+}}

data/lib/nuggets/all.rb

@@ -0,0 +1,34 @@
+#--
+###############################################################################
+#                                                                             #
+# A component of ruby-nuggets, some extensions to the Ruby programming        #
+# language.                                                                   #
+#                                                                             #
+# Copyright (C) 2007 Jens Wille                                               #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@uni-koeln.de>                                    #
+#                                                                             #
+# ruby-nuggets is free software; you can redistribute it and/or modify it     #
+# under the terms of the GNU General Public License as published by the Free  #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# ruby-nuggets is distributed in the hope that it will be useful, but WITHOUT #
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or       #
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for    #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU General Public License along     #
+# with ruby-nuggets. If not, see <http://www.gnu.org/licenses/>.              #
+#                                                                             #
+###############################################################################
+#++
+
+base = File.dirname(__FILE__)
+base_re = Regexp.escape(base)
+
+Dir[File.join(base, %w[* ** *.rb])].sort.each { |path|
+  ext_re = Regexp.escape(File.extname(path))
+  require path.sub(/#{base_re}(.*)#{ext_re}/, 'nuggets\1')
+}

data/lib/nuggets/array/combination.rb

@@ -0,0 +1,86 @@
+#--
+###############################################################################
+#                                                                             #
+# A component of ruby-nuggets, some extensions to the Ruby programming        #
+# language.                                                                   #
+#                                                                             #
+# Copyright (C) 2007 Jens Wille                                               #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@uni-koeln.de>                                    #
+#                                                                             #
+# ruby-nuggets is free software; you can redistribute it and/or modify it     #
+# under the terms of the GNU General Public License as published by the Free  #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# ruby-nuggets is distributed in the hope that it will be useful, but WITHOUT #
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or       #
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for    #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU General Public License along     #
+# with ruby-nuggets. If not, see <http://www.gnu.org/licenses/>.              #
+#                                                                             #
+###############################################################################
+#++
+
+class Array
+
+  # call-seq:
+  #   array.comb(n, ...) => new_array
+  #   array.comb(n, ...) { |combination| ... } => new_array
+  #
+  # Returns an array of arrays of each possible +n+-combination of _array_ for each
+  # given +n+. If a block is given, each +combination+ is yielded to it. Based on
+  # <http://blade.nagaokaut.ac.jp/~sinara/ruby/math/combinatorics/array-comb.rb>.
+  def comb(*sizes)
+    # If no sizes are given, produce all!
+    sizes = (0..size).to_a.reverse if sizes.empty?
+
+    # Container for our combinations
+    combinations = []
+
+    # Collect combinations and, optionally, yield to block.
+    collect_and_yield = lambda { |combination|
+      combinations << combination
+
+      yield(combination) if block_given?
+    }
+
+    sizes.each { |n|
+      case n
+        when 0        # Short-cut (breaks recursion)
+          collect_and_yield[[]]
+        when 1..size  # Ignore out-of-range values
+          self[1..-1].comb(n - 1) { |combination|
+            collect_and_yield[combination.unshift(first)]
+          }
+          self[1..-1].comb(n) { |combination|
+            collect_and_yield[combination]
+          }
+      end
+    }
+
+    # Anyway, return what we've found...
+    combinations
+  end
+
+end
+
+if $0 == __FILE__
+  a = %w[a b c d]
+  p a
+
+  p a.comb(3)
+  a.comb(3) { |x|
+    p x
+  }
+
+  p a.comb(4, 2, 4)
+
+  p a.comb
+  a.comb { |x|
+    p x
+  }
+end

data/lib/nuggets/array/flatten_once.rb

@@ -0,0 +1,68 @@
+#--
+###############################################################################
+#                                                                             #
+# A component of ruby-nuggets, some extensions to the Ruby programming        #
+# language.                                                                   #
+#                                                                             #
+# Copyright (C) 2007 Jens Wille                                               #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@uni-koeln.de>                                    #
+#                                                                             #
+# ruby-nuggets is free software; you can redistribute it and/or modify it     #
+# under the terms of the GNU General Public License as published by the Free  #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# ruby-nuggets is distributed in the hope that it will be useful, but WITHOUT #
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or       #
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for    #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU General Public License along     #
+# with ruby-nuggets. If not, see <http://www.gnu.org/licenses/>.              #
+#                                                                             #
+###############################################################################
+#++
+
+class Array
+
+  # call-seq:
+  #   array.flatten_once => new_array
+  #
+  # Flatten _array_ by _one_ level only. Pretty straight-forward port of David
+  # Alan Black's flattenx C implementation (though much slower, of course ;-).
+  def flatten_once
+    flat = []
+
+    each { |element|
+      if element.is_a?(Array)
+        flat += element
+      else
+        flat << element
+      end
+    }
+
+    flat
+  end
+
+  # call-seq:
+  #   array.flatten_once! => array
+  #
+  # Destructive version of #flatten_once.
+  def flatten_once!
+    replace flatten_once
+  end
+
+end
+
+if $0 == __FILE__
+  a = [1, 2, [3, 4, 5], 6, [7, [8, 9]]]
+  p a
+
+  p a.flatten
+  p a.flatten_once
+
+  a.flatten_once!
+  p a
+end

data/lib/nuggets/array/format.rb

@@ -0,0 +1,124 @@
+#--
+###############################################################################
+#                                                                             #
+# A component of ruby-nuggets, some extensions to the Ruby programming        #
+# language.                                                                   #
+#                                                                             #
+# Copyright (C) 2007 Jens Wille                                               #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@uni-koeln.de>                                    #
+#                                                                             #
+# ruby-nuggets is free software; you can redistribute it and/or modify it     #
+# under the terms of the GNU General Public License as published by the Free  #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# ruby-nuggets is distributed in the hope that it will be useful, but WITHOUT #
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or       #
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for    #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU General Public License along     #
+# with ruby-nuggets. If not, see <http://www.gnu.org/licenses/>.              #
+#                                                                             #
+###############################################################################
+#++
+
+require 'nuggets/array/combination'
+
+class Array
+
+  # call-seq:
+  #   array % other_array => aString
+  #   array % str         => aString
+  #
+  # Format--Uses the first string in _array_ for which the corresponding
+  # combination of _other_array_ does not contain blank elements as a format
+  # specification, and returns the result of applying it to that combination
+  # (cf. String#%). Returns an empty string if _other_array_ is empty.
+  #
+  # Applies to string argument accordingly: First string in _array_ applied to
+  # _str_; empty string if _str_ is empty.
+  def %(args)
+    opts = { :sep => ', ' }
+    opts.update(pop) if last.is_a?(Hash)
+
+    default = lambda { |n|
+      ['%s'] * n * opts[:sep]
+    }
+
+    case args
+      when String
+        return (first || default[1]) % args unless
+          args.nil? || args.empty?
+      when Array
+        i = 0
+        [*args].comb { |x|
+          return (self[i] || default[x.size]) % x unless
+            x.empty? || x.any? { |y|
+              y.nil? || y.empty?
+            }
+
+          i += 1
+        }
+    end
+
+    ''
+  end
+
+end
+
+if $0 == __FILE__
+  [[], 'string', ''].each { |x|
+    p x
+    puts '>> ' << ['"%s"'] % x
+  }
+
+  [ ['place', 'country'],
+    ['place', ''       ],
+    ['',      'country'],
+    ['',      ''       ]
+  ].each { |x|
+    p x
+    puts '>> ' << ['%s, (%s)', '%s', '(%s)'] % x
+  }
+
+  puts '=' * 80
+
+  [ ['author', 'title', 'year'],
+    ['author', 'title', ''    ],
+    ['author', '',      'year'],
+    ['',       'title', 'year'],
+    ['author', ''     , ''    ],
+    ['',       'title', ''    ],
+    ['',       '',      'year'],
+    ['',       '',      ''    ]
+  ].each { |x|
+    p x
+    puts '>> ' << ['%s: %s (%s)', '%s: %s', '%s (%s)', '%s (%s)'] % x
+  }
+
+  puts '=' * 80
+
+  [ ['1', '2', '3', '4'],
+    ['1', '2', '3', '' ],
+    ['1', '2', '',  '4'],
+    ['1', '',  '3', '4'],
+    ['',  '2', '3', '4'],
+    ['1', '2', '',  '' ],
+    ['1', '',  '3', '' ],
+    ['1', '',  '',  '4'],
+    ['',  '2', '3', '' ],
+    ['',  '2', '',  '4'],
+    ['',  '',  '3', '4'],
+    ['1', '',  '',  '' ],
+    ['',  '2', '',  '' ],
+    ['',  '',  '3', '' ],
+    ['',  '',  '',  '4'],
+    ['',  '',  '',  '' ]
+  ].each { |x|
+    p x
+    puts '>> ' << [{ :sep => ':' }] % x
+  }
+end

data/lib/nuggets/array/in_order.rb

@@ -0,0 +1,62 @@
+#--
+###############################################################################
+#                                                                             #
+# A component of ruby-nuggets, some extensions to the Ruby programming        #
+# language.                                                                   #
+#                                                                             #
+# Copyright (C) 2007 Jens Wille                                               #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@uni-koeln.de>                                    #
+#                                                                             #
+# ruby-nuggets is free software; you can redistribute it and/or modify it     #
+# under the terms of the GNU General Public License as published by the Free  #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# ruby-nuggets is distributed in the hope that it will be useful, but WITHOUT #
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or       #
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for    #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU General Public License along     #
+# with ruby-nuggets. If not, see <http://www.gnu.org/licenses/>.              #
+#                                                                             #
+###############################################################################
+#++
+
+class Array
+
+  # call-seq:
+  #   array.in_order(*ordered) => new_array
+  #
+  # Force order, but ignore non-existing and keep remaining.
+  #
+  # Examples:
+  #   [:created_at, :email, :login, :updated_at].in_order(:login, :email)    #=> [:login, :email, :created_at, :updated_at]
+  #   [:created_at, :email, :login, :updated_at].in_order(:email, :address)  #=> [:email, :created_at, :login, :updated_at]
+  def in_order(*ordered)
+    ordered &= self
+    ordered + (self - ordered)
+  end
+
+  # call-seq:
+  #   array.in_order!(*ordered) => array
+  #
+  # Destructive version of #in_order.
+  def in_order!(*ordered)
+    replace in_order(*ordered)
+  end
+
+end
+
+if $0 == __FILE__
+  a = [:created_at, :email, :login, :updated_at]
+  p a
+
+  p a.in_order(:login, :email)
+  p a.in_order(:email, :address)
+
+  a.in_order!(:login, :email)
+  p a
+end

data/lib/nuggets/array/monotone.rb

@@ -0,0 +1,101 @@
+#--
+###############################################################################
+#                                                                             #
+# A component of ruby-nuggets, some extensions to the Ruby programming        #
+# language.                                                                   #
+#                                                                             #
+# Copyright (C) 2007 Jens Wille                                               #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@uni-koeln.de>                                    #
+#                                                                             #
+# ruby-nuggets is free software; you can redistribute it and/or modify it     #
+# under the terms of the GNU General Public License as published by the Free  #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# ruby-nuggets is distributed in the hope that it will be useful, but WITHOUT #
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or       #
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for    #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU General Public License along     #
+# with ruby-nuggets. If not, see <http://www.gnu.org/licenses/>.              #
+#                                                                             #
+###############################################################################
+#++
+
+class Array
+
+  # call-seq:
+  #   array.monotone?(operator) => true or false
+  #
+  # Check whether _array_ is monotone according to +operator+.
+  def monotone?(operator)
+    inject { |a, b|
+      return false unless a.send(operator, b)
+      b
+    }
+
+    true
+  end
+  alias_method :monotonic?, :monotone?
+
+  # call-seq:
+  #   array.ascending? => true or false
+  #
+  # Check whether _array_ is (strictly) ascending.
+  def ascending?(strict = false)
+    monotone?(strict ? :< : :<=)
+  end
+  alias_method :increasing?, :ascending?
+
+  # call-seq:
+  #   array.strictly_ascending? => true or false
+  #
+  # Check whether _array_ is strictly ascending.
+  def strictly_ascending?
+    ascending?(true)
+  end
+  alias_method :strictly_increasing?, :strictly_ascending?
+
+  # call-seq:
+  #   array.descending? => true or false
+  #
+  # Check whether _array_ is (strictly) descending.
+  def descending?(strict = false)
+    monotone?(strict ? :> : :>=)
+  end
+  alias_method :decreasing?, :descending?
+
+  # call-seq:
+  #   array.strictly_descending? => true or false
+  #
+  # Check whether _array_ is strictly descending.
+  def strictly_descending?
+    descending?(true)
+  end
+  alias_method :strictly_decreasing?, :strictly_descending?
+
+end
+
+if $0 == __FILE__
+  a = [1, 2, 3, 4]
+  p a
+
+  p a.ascending?           # => true
+  p a.strictly_ascending?  # => true
+  p a.descending?          # => false
+
+  b = [1, 2, 4, 3]
+  p b
+
+  p b.ascending?           # => false
+  p b.descending?          # => false
+
+  c = [1, 2, 4, 4]
+  p c
+
+  p c.ascending?           # => true
+  p c.strictly_ascending?  # => false
+end

data/lib/nuggets/array/only.rb

@@ -0,0 +1,56 @@
+#--
+###############################################################################
+#                                                                             #
+# A component of ruby-nuggets, some extensions to the Ruby programming        #
+# language.                                                                   #
+#                                                                             #
+# Copyright (C) 2007-2008 Jens Wille                                          #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@uni-koeln.de>                                    #
+#                                                                             #
+# ruby-nuggets is free software; you can redistribute it and/or modify it     #
+# under the terms of the GNU General Public License as published by the Free  #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# ruby-nuggets is distributed in the hope that it will be useful, but WITHOUT #
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or       #
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for    #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU General Public License along     #
+# with ruby-nuggets. If not, see <http://www.gnu.org/licenses/>.              #
+#                                                                             #
+###############################################################################
+#++
+
+class Array
+
+  # call-seq:
+  #   array.only(relax = true or false) => anObject
+  #
+  # Returns the only element of _array_. Raises an IndexError if _array_'s
+  # size is not 1, unless +relax+ is true.
+  #
+  # Idea stolen from Gavin Sinclair's Ruby Extensions Project.
+  def only(relax = size == 1)
+    raise IndexError, 'not a single-element array' unless relax
+    first
+  end
+
+end
+
+if $0 == __FILE__
+  [[5], [1, 2, 3], []].each { |a|
+    p a
+
+    begin
+      p a.only
+    rescue IndexError => err
+      warn err
+    end
+
+    p a.only(true)
+  }
+end

data/lib/nuggets/array/rand.rb

@@ -0,0 +1,45 @@
+#--
+###############################################################################
+#                                                                             #
+# A component of ruby-nuggets, some extensions to the Ruby programming        #
+# language.                                                                   #
+#                                                                             #
+# Copyright (C) 2007 Jens Wille                                               #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@uni-koeln.de>                                    #
+#                                                                             #
+# ruby-nuggets is free software; you can redistribute it and/or modify it     #
+# under the terms of the GNU General Public License as published by the Free  #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# ruby-nuggets is distributed in the hope that it will be useful, but WITHOUT #
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or       #
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for    #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU General Public License along     #
+# with ruby-nuggets. If not, see <http://www.gnu.org/licenses/>.              #
+#                                                                             #
+###############################################################################
+#++
+
+class Array
+
+  # call-seq:
+  #   array.rand => anItem
+  #
+  # Randomly pick an item from _array_.
+  def rand
+    at(Kernel.rand(size))
+  end
+
+end
+
+if $0 == __FILE__
+  a = %w[a b c d]
+  p a
+  p a.rand
+  p a.rand
+end