blackwinter-ruby-nuggets 0.4.0

data/lib/nuggets/file/which.rb

@@ -0,0 +1,74 @@
+#--
+###############################################################################
+#                                                                             #
+# 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 File
+
+  class << self
+
+    # call-seq:
+    #   File.which(executable) => aString or nil
+    #
+    # Returns the full path to +executable+, or +nil+ if not found in PATH.
+    # Inspired by Gnuplot.which -- thx, Gordon!
+    def which(executable)
+      return executable if executable?(executable)
+
+      if path = ENV['PATH']
+        path.split(PATH_SEPARATOR).each { |dir|
+          candidate = join(dir, executable)
+          return candidate if executable?(candidate)
+        }
+      end
+
+      nil
+    end
+
+    # call-seq:
+    #   File.which_command(commands) => aString or nil
+    #
+    # Returns the first of +commands+ that is executable.
+    def which_command(commands)
+      commands.find { |command| which(command[/\S+/]) }
+    end
+
+  end
+
+end
+
+if $0 == __FILE__
+  %w[cat dog rat gcc /usr/bin/X11/gcc].each { |e|
+    p [e, File.which(e)]
+  }
+
+  c = [
+    'unison --args source target',
+    'rsync --args source target',
+    'scp --args source target'
+  ]
+  p c
+  p File.which_command(c)
+end

data/lib/nuggets/hash/at.rb

@@ -0,0 +1,87 @@
+#--
+###############################################################################
+#                                                                             #
+# 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/>.              #
+#                                                                             #
+###############################################################################
+#++
+
+require 'nuggets/array/rand'
+
+class Hash
+
+  # call-seq:
+  #   hash.at(what) => aHash
+  #
+  # Returns the key/value pair of _hash_ at key position +what+. Remember that
+  # hashes might not have the intended (or expected) order in pre-1.9 Ruby.
+  def at(what)
+    return {} if empty?
+
+    key = case what
+      when Integer
+        keys[what]
+      else
+        block_given? ? keys.send(*what) { |*a| yield(*a) } : keys.send(*what)
+    end
+
+    { key => self[key] }
+  end
+
+  # call-seq:
+  #   hash.first => aHash
+  #
+  # Returns the "first" key/value pair of _hash_.
+  def first
+    at(:first)
+  end
+
+  # call-seq:
+  #   hash.last => aHash
+  #
+  # Returns the "last" key/value pair of _hash_.
+  def last
+    at(:last)
+  end
+
+  # call-seq:
+  #   hash.rand => aHash
+  #
+  # Returns a random key/value pair of _hash_.
+  def rand
+    at(:rand)
+  end
+
+end
+
+if $0 == __FILE__
+  h = { :a => 1, 2 => 3, nil => nil, 'foo' => %w[b a r]}
+  p h
+
+  p h.first
+  p h.last
+  p h.rand
+
+  p h.at(0)
+  p h.at(1)
+  p h.at(-1)
+end

data/lib/nuggets/hash/in_order.rb

@@ -0,0 +1,52 @@
+#--
+###############################################################################
+#                                                                             #
+# 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/>.              #
+#                                                                             #
+###############################################################################
+#++
+
+require 'nuggets/array/in_order'
+
+class Hash
+
+  # call-seq:
+  #   hash.in_order(*ordered) => anArray
+  #
+  # Returns <tt>hash#to_a</tt>, in forced order (cf. Array#in_order).
+  #
+  # Examples:
+  #   { :a => 1, :b => 2, :c => 3 }.in_order(:b, :c)  #=> [[:b, 2], [:c, 3], [:a, 1]]
+  #   { :a => 1, :b => 2, :c => 3 }.in_order(:b, :d)  #=> [[:b, 2], [:a, 1], [:c, 3]]
+  def in_order(*ordered)
+    keys.in_order(*ordered).map { |key| [key, self[key]] }
+  end
+
+end
+
+if $0 == __FILE__
+  a = { :a => 1, :b => 2, :c => 3 }
+  p a
+
+  p a.in_order(:b, :c)
+  p a.in_order(:b, :d)
+end

data/lib/nuggets/hash/insert.rb

@@ -0,0 +1,65 @@
+#--
+###############################################################################
+#                                                                             #
+# 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 Hash
+
+  # call-seq:
+  #   hash.insert(other) => new_hash
+  #   hash.insert(other) { |key, old_value, new_value| ... } => new_hash
+  #
+  # Inserts +other+ into _hash_, while merging existing values instead of just
+  # overwriting. Uses default Hash#merge or block for merging.
+  def insert(other, &block)
+    block ||= lambda { |key, old_val, new_val|
+      old_val.is_a?(Hash) && new_val.is_a?(Hash) ?
+        old_val.merge(new_val, &block) : new_val
+    }
+
+    merge(other, &block)
+  end
+
+  # call-seq:
+  #   hash.insert!(other) => hash
+  #   hash.insert!(other) { |key, old_value, new_value| ... } => hash
+  #
+  # Destructive version of #insert.
+  def insert!(other)
+    replace block_given? ? insert(other) { |*a| yield(*a) } : insert(other)
+  end
+
+end
+
+if $0 == __FILE__
+  h = { :a => 0, :b => { :b1 => 1, :b2 => 2 } }
+  p h
+
+  p h.insert(:a => -1)
+  p h.insert(:b => { :b3 => 3 })
+
+  h.insert!(:b => { :b0 => 0 })
+  p h
+end

data/lib/nuggets/hash/only.rb

@@ -0,0 +1,68 @@
+#--
+###############################################################################
+#                                                                             #
+# 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/>.              #
+#                                                                             #
+###############################################################################
+#++
+
+require 'nuggets/hash/at'
+
+class Hash
+
+  # call-seq:
+  #   hash.only(relax = true or false) => aHash
+  #
+  # Returns the only key/value pair of _hash_. Raises an IndexError if _hash_'s
+  # size is not 1, unless +relax+ is true.
+  def only(relax = size == 1, split = false)
+    raise IndexError, 'not a single-element hash' unless relax
+
+    return *first if split
+    first
+  end
+
+  # call-seq:
+  #   hash.only_pair(relax = true or false) => anArray
+  #
+  # Returns the only key/value pair of _hash_ as an array. Raises an IndexError
+  # if _hash_'s size is not 1, unless +relax+ is true.
+  def only_pair(relax = size == 1)
+    only(relax, true)
+  end
+
+end
+
+if $0 == __FILE__
+  [{ :a => 5 }, { 1 => 2, 3 => 4 }, {}].each { |h|
+    p h
+
+    begin
+      p h.only
+      p h.only_pair
+    rescue IndexError => err
+      warn err
+    end
+
+    p h.only(true)
+  }
+end

data/lib/nuggets/integer/factorial.rb

@@ -0,0 +1,74 @@
+#--
+###############################################################################
+#                                                                             #
+# 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 Integer
+
+  # Memoization container: integer => factorial(integer)
+  FACTORIAL = { 0 => 1 }
+
+  # call-seq:
+  #   int.factorial => anInteger
+  #
+  # Calculate the factorial of _int_. To use the memoized version:
+  # <tt>Integer.send(:alias_method, :factorial, :factorial_memoized)</tt>
+  def factorial
+    (1..self).inject { |f, i| f * i }
+  end
+
+  # call-seq:
+  #   int.factorial_memoized => anInteger
+  #
+  # Calculate the factorial of _int_ with the help of memoization (Which gives
+  # a considerable speedup for repeated calculations -- at the cost of memory).
+  #
+  # WARNING: Don't try to calculate the factorial this way for "large"
+  # integers! This might well bring your system down to its knees... ;-)
+  def factorial_memoized
+    FACTORIAL[self] ||= (1..self).inject { |f, i| FACTORIAL[i] ||= f * i }
+  end
+
+  alias_method :fac, :factorial
+  alias_method :f!,  :factorial
+
+end
+
+if $0 == __FILE__
+  1.upto(8) { |i|
+    puts "#{i}: #{i.factorial}"
+  }
+
+  require 'benchmark'
+
+  Benchmark.bm(19) { |x|
+    [20000, 800, 300, 700, 130, 480, 9999, 9999, 25000].each { |i|
+      puts "#{i}:"
+
+      x.report('factorial')          { i.factorial          }
+      x.report('factorial_memoized') { i.factorial_memoized }
+    }
+  }
+end

data/lib/nuggets/integer/to_binary_s.rb

@@ -0,0 +1,47 @@
+#--
+###############################################################################
+#                                                                             #
+# 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 Integer
+
+  # call-seq:
+  #   int.to_binary_s => aString
+  #   int.to_binary_s(length) => aString
+  #
+  # Returns _int_ as binary number string; optionally zero-padded to +length+.
+  def to_binary_s(length = nil)
+    "%0#{length}d" % to_s(2)
+  end
+
+end
+
+if $0 == __FILE__
+  [20000, 800, 300, 700, 130, 480, 9999, 9999, 25000].each { |i|
+    p i
+    p i.to_binary_s
+    p i.to_binary_s(32)
+  }
+end

data/lib/nuggets/io/agrep.rb

@@ -0,0 +1,43 @@
+#--
+###############################################################################
+#                                                                             #
+# 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/>.              #
+#                                                                             #
+###############################################################################
+#++
+
+require 'nuggets/enumerable/agrep'
+
+class IO
+
+  # call-seq:
+  #   IO.agrep(fd, pattern[, distance]) => anArray
+  #
+  def self.agrep(fd, pattern, distance)
+    open(fd) { |io| io.agrep(pattern, distance) }
+  end
+
+end
+
+if $0 == __FILE__
+  puts File.agrep(__FILE__, /calls/, 2)
+end

data/lib/nuggets/io/modes.rb

@@ -0,0 +1,133 @@
+#--
+###############################################################################
+#                                                                             #
+# 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 IO
+
+  # Inspired by Martin DeMello, [ruby-talk:307782] -- thx ;-)
+
+  class << self
+
+    alias_method :_nuggets_original_read, :read
+
+    # call-seq:
+    #   IO.read(name, [length [, offset]]) => aString
+    #   IO.read(name, binary = false) { |io| ... } => anObject
+    #
+    # Opens +name+ with mode +r+. NOTE: With no associated block,
+    # acts like the original IO::read, not like IO::new.
+    def read(name, *args)
+      return _nuggets_original_read(name, *args) unless block_given?
+
+      case args.size
+        when 0
+          # ok
+        when 1
+          case binary = args.first
+            when true, false, nil
+              # ok
+            else
+              raise TypeError, "wrong argument type #{binary.class} (expected boolean)"
+          end
+        else
+          raise ArgumentError, "wrong number of arguments (#{args.size + 1} for 1-2)"
+      end
+
+      open_with_mode(name, 'r', binary) { |*a| yield(*a) }
+    end
+
+    # call-seq:
+    #   IO.write(name, binary = false) => anIO
+    #   IO.write(name, binary = false) { |io| ... } => anObject
+    #
+    # Opens +name+ with mode +w+.
+    def write(name, binary = false)
+      block_given? ?
+        open_with_mode(name, 'w', binary) { |*a| yield(*a) } :
+        open_with_mode(name, 'w', binary)
+    end
+
+    # call-seq:
+    #   IO.append(name, binary = false) => anIO
+    #   IO.append(name, binary = false) { |io| ... } => anObject
+    #
+    # Opens +name+ with mode +a+.
+    def append(name, binary = false)
+      block_given? ?
+        open_with_mode(name, 'a', binary) { |*a| yield(*a) } :
+        open_with_mode(name, 'a', binary)
+    end
+
+    # call-seq:
+    #   IO.read_write(name, binary = false) => anIO
+    #   IO.read_write(name, binary = false) { |io| ... } => anObject
+    #
+    # Opens +name+ with mode <tt>r+</tt>.
+    def read_write(name, binary = false)
+      block_given? ?
+        open_with_mode(name, 'r+', binary) { |*a| yield(*a) } :
+        open_with_mode(name, 'r+', binary)
+    end
+
+    # call-seq:
+    #   IO.write_read(name, binary = false) => anIO
+    #   IO.write_read(name, binary = false) { |io| ... } => anObject
+    #
+    # Opens +name+ with mode <tt>w+</tt>.
+    def write_read(name, binary = false)
+      block_given? ?
+        open_with_mode(name, 'w+', binary) { |*a| yield(*a) } :
+        open_with_mode(name, 'w+', binary)
+    end
+
+    # call-seq:
+    #   IO.append_read(name, binary = false) => anIO
+    #   IO.append_read(name, binary = false) { |io| ... } => anObject
+    #
+    # Opens +name+ with mode <tt>a+</tt>.
+    def append_read(name, binary = false)
+      block_given? ?
+        open_with_mode(name, 'a+', binary) { |*a| yield(*a) } :
+        open_with_mode(name, 'a+', binary)
+    end
+
+    private
+
+    # Just a helper to DRY things up.
+    def open_with_mode(name, mode, binary = false)
+      mode << 'b' if binary
+      block_given? ? open(name, mode) { |io| yield io } : open(name, mode)
+    end
+
+  end
+
+end
+
+if $0 == __FILE__
+  # File.read(__FILE__) { |f| ... }
+  # File.write(__FILE__) { |f| ... }
+  # File.append(__FILE__) { |f| ... }
+end

data/lib/nuggets/numeric/between.rb

@@ -0,0 +1,2 @@
+# backwards compatibility
+require 'nuggets/numeric/limit'