facets 0.6.3

data/lib/facet/fileutils/whereis.rb

@@ -0,0 +1,63 @@
+#--
+# Credit goes to Daniel J. Berger, via PTools.
+#++
+require 'fileutils'
+
+module FileUtils
+  if defined?(Win32Exts)
+    Win32Exts ||= %w{.exe .com .bat}
+  else
+    Win32Exts = %w{.exe .com .bat}
+  end
+    
+  # In block form, yields each ((*program*)) within ((*path*)).  In non-block
+  # form, returns an array of each ((*program*)) within ((*path*)).  Returns
+  # (({nil})) if not found.
+  #  
+  # On the MS Windows platform, it looks for executables ending with .exe,
+  # .bat and .com, which you may optionally include in the program name.
+  #
+  #    File.whereis("ruby") -> ['/usr/local/bin/ruby','/opt/bin/ruby']
+  #
+  def self.whereis(prog, path=ENV['PATH']) #:yield:
+    dirs = []
+    path.split(File::PATH_SEPARATOR).each{|dir|
+        # Windows checks against specific extensions
+        if File::ALT_SEPARATOR
+          if prog.include?('.')
+              f = File.join(dir,prog)
+              if File.executable?(f) && !File.directory?(f)
+                if block_given?
+                    yield f.gsub(/\//,'\\')
+                else
+                    dirs << f.gsub(/\//,'\\')
+                end
+              end
+          else
+              Win32Exts.find_all{|ext|
+                f = File.join(dir,prog+ext)
+                if File.executable?(f) && !File.directory?(f)
+                    if block_given?
+                      yield f.gsub(/\//,'\\')
+                    else
+                      dirs << f.gsub(/\//,'\\')
+                    end
+                end
+              }
+          end
+        else
+          f = File.join(dir,prog)
+          # Avoid /usr/lib/ruby, for example
+          if File.executable?(f) && !File.directory?(f)
+              if block_given?
+                yield f
+              else
+                dirs << f
+              end
+          end
+        end
+    }
+    dirs.empty? ? nil : dirs
+  end
+
+end 

data/lib/facet/fileutils/which.rb

@@ -0,0 +1,53 @@
+#--
+# The which() method was adopted from Daniel J. Berger, via PTools 
+# which in in turn was adopted fromt the FileWhich code posted by 
+# Michael Granger on http://www.rubygarden.org.
+#++
+require 'fileutils'
+
+module FileUtils
+  if defined?(Win32Exts)
+    Win32Exts ||= %w{.exe .com .bat}
+  else
+    Win32Exts = %w{.exe .com .bat}
+  end
+  
+  # Looks for the first occurrence of _program_ within _path_.
+  #  
+  # On the MS Windows platform, it looks for executables ending with .exe,
+  # .bat and .com, which you may optionally include in the program name.
+  # Returns <tt>nil</tt> if not found.
+  #
+  def self.which(prog, path=ENV['PATH'])
+    path.split(File::PATH_SEPARATOR).each {|dir|
+        # Windows checks against specific extensions
+        if File::ALT_SEPARATOR
+          ext = Win32Exts.find{|ext|
+              if prog.include?('.') # Assume extension already included
+                f = File.join(dir,prog)
+              else
+                f = File.join(dir,prog+ext)
+              end 
+              File.executable?(f) && !File.directory?(f) 
+          }
+          if ext
+              # Use backslashes, not forward slashes
+              if prog.include?('.') # Assume extension already included
+                f = File.join( dir, prog ).gsub(/\//,'\\')
+              else
+                f = File.join( dir, prog + ext ).gsub(/\//,'\\')
+              end
+              return f
+          end
+        else
+          f = File.join(dir,prog)
+          # Avoid /usr/lib/ruby, for example
+          if File.executable?(f) && !File.directory?(f)
+            return File::join( dir, prog )
+          end
+        end
+    }
+    nil
+  end
+  
+end 

data/lib/facet/float.rb

@@ -0,0 +1,7 @@
+
+# base
+
+# common
+require "facet/float/round"
+
+# uncommon

data/lib/facet/float/round.rb

@@ -0,0 +1,33 @@
+class Float
+  # Rounds off at the given decimal position.
+  def round_at( d=0.0 )
+    (self * (10.0 ** d)).round.to_f / (10.0 ** d)
+  end
+  # Rounds to the nearest _n_th. If no _n_th is
+  # given, then defaults to nearest 100th.
+  def round_to( n=0.01 )
+    raise ArgumentError, "zero equates to infinte degree" if n == 0
+    (self * (1.0 / n)).round.to_f / (1.0 / n)
+  end
+  # Determines if another number is approximately equal
+  # within a given _n_th degree. Defaults to 100ths
+  # if degree is not specified.
+  def approx?( x, n=0.01 )
+    raise ArgumentError, "zero equates to infinte degree" if n == 0
+    self.round_to(n) == x.to_f.round_to(n)
+  end
+end
+
+# To properly support Float rounding methods,
+# Numeric must also be augmented.
+class Numeric
+  def round_at(*args)
+    self.to_f.round_at(*args)
+  end
+  def round_to(*args)
+    self.to_f.round_to(*args)
+  end
+  def approx?(*args)
+    self.to_f.approx?(*args)
+  end
+end

data/lib/facet/hash.rb

@@ -0,0 +1,23 @@
+
+# base
+require "facet/hash/to_h"
+
+# common
+require "facet/hash/to_ostruct"
+
+# uncommon
+#require "facet/hash/alias!"
+#require "facet/hash/at_rand"
+#require "facet/hash/collate"
+#require "facet/hash/each"
+#require "facet/hash/keys_to_string"
+#require "facet/hash/keys_to_symbol"
+#require "facet/hash/<<"
+#require "facet/hash/[]"
+#require "facet/hash/slice"
+#require "facet/hash/swapkey!"
+#require "facet/hash/swap!"
+#require "facet/hash/traverse"
+#require "facet/hash/update_each"
+#require "facet/hash/weave"
+#require "facet/hash/zipnew"

data/lib/facet/hash/<<.rb

@@ -0,0 +1,5 @@
+class Hash
+  # Alias shorthand for #update.
+  alias_method( :<<, :update )
+end
+

data/lib/facet/hash/[].rb

@@ -0,0 +1,44 @@
+class Hash
+  
+  alias_method( :at, :[] )
+  
+  # Adds slicing to Hash#[]. If more than one key arguments
+  # is given to <tt>Hash#[]</tt>, the return value will be 
+  # an array of the corresponding values.
+  #
+  #   require "facet/hash/[]"
+  # 
+  #   h = { :a => 1, :b => 2, :c => 3 }
+  #   h[:a]            #=> 1
+  #   h[:a, :b]        #=> [1,2]
+  #
+  def []( *sliceKeys )
+    if sliceKeys.length == 1
+      return at( sliceKeys[0] )
+    else
+      return values_at( *sliceKeys )
+    end
+  end
+  
+  # Add slicing to element assignment operator.
+  #
+  #   require "facet/hash/[]"
+  #
+  #   h = {:a=>1, :b=>2, :c=>3}
+  #
+  #   h[:a] = 9              #=> 9
+  #   h                      #=> {:a=>9, :b=>2, :c=>3}
+  #
+  #   h[:a, :c] = [10,11]    #=> [10,11]
+  #   h                      #=> {:a=>10, :b=>2, :c=>11}
+  #
+  def []=( *args )
+    if args.length <= 2
+      return store( *args )
+    end
+    aVals = args.pop
+    aVals = [aVals] unless aVals.kind_of?( Array )
+    args.each_index{ |i| store( args[i], aVals[i] ) }
+  end
+
+end

data/lib/facet/hash/alias!.rb

@@ -0,0 +1,24 @@
+#--
+# Credit goes to Gavin Sinclair.
+#++
+class Hash
+  # Modifies the receiving Hash so that the value previously referred to by 
+  # _oldkey_ is also referenced by _newkey_; _oldkey_ is retained in the Hash.
+  # If _oldkey_ does not exist as a key in the Hash, no change is effected.
+  #
+  # Returns a reference to the Hash.
+  #
+  #   require 'facet/hash/alias!'
+  #
+  #   foo = { :name=>'Gavin', 'wife'=>:Lisa }
+  #   foo.alias!('name',:name)     => { :name=>'Gavin', 'name'=>'Gavin', 'wife'=>:Lisa }
+  #   foo.alias!('spouse','wife')  => { :name=>'Gavin', 'name'=>'Gavin', 'wife'=>:Lisa, 'spouse'=>:Lisa }
+  #   foo.alias!('bar','foo')      => { :name=>'Gavin', 'name'=>'Gavin', 'wife'=>:Lisa, 'spouse'=>:Lisa }
+  #
+  # Note that if the _oldkey_ is reassigned, the reference will no longer exist,
+  # and the _newkey_ will remain as it was.
+  def alias!( newkey, oldkey )
+    self[newkey] = self[oldkey] if self.has_key?(oldkey)
+    self
+  end
+end 

data/lib/facet/hash/at_rand.rb

@@ -0,0 +1,88 @@
+#--
+# Adapted from rand.rb by:
+# * Ilmari Heikkinen <mailto:kig@misfiring.net>
+# * Christian Neukirchen <mailto:chneukirchen@gmail.com>
+#++
+class Hash
+
+  # Returns a random key-value pair.
+  #
+  #   require 'facet/hash/at_rand'
+  #
+  #   {:one => 1, :two => 2, :three => 3}.at_rand  #=> [:one, 1]
+  #
+  def rand_value
+    fetch( rand_key )
+  end
+  alias( :at_rand, :rand_value )
+
+  # Deletes a random key-value pair and returns the value.
+  #
+  #   require 'facet/hash/at_rand'
+  #
+  #   a = {:one => 1, :two => 2, :three => 3}
+  #   a.at_rand!  #=> 2
+  #   a           #=> {:one => 1, :three => 3}
+  #
+  def rand_value!
+    k,v = rand_pair
+    delete( k )
+    return v
+  end
+  alias_method( :at_rand!, :rand_value! )
+  alias_method( :pick, :at_rand! )
+  
+  # Returns a random key.
+  #
+  #   require 'facet/hash/at_rand'
+  #
+  #   {:one => 1, :two => 2, :three => 3}.pick_key  #=> :three
+  #
+  def rand_key
+    keys.at( rand(keys.size) )
+  end
+
+  # Delete a random key-value pair, returning the key.
+  #
+  #   require 'facet/hash/at_rand'
+  #
+  #   a = {:one => 1, :two => 2, :three => 3}
+  #   a.pick_key!  #=> :two
+  #   a            #=> {:one => 1, :three => 3}
+  #
+  def rand_key!
+    k,v = rand_pair
+    delete( k )
+    return k
+  end
+  alias( :pick_key, :rand_key! )
+
+  # Returns a random key-value pair.
+  #
+  #   require 'facet/hash/at_rand'
+  #
+  #   {:one => 1, :two => 2, :three => 3}.pick  #=> [:one, 1]
+  #
+  def rand_pair
+    k = rand_key
+    return k, fetch(k)
+  end
+
+  # Deletes a random key-value pair and returns that pair.
+  #
+  #   require 'facet/hash/at_rand'
+  #
+  #   a = {:one => 1, :two => 2, :three => 3}
+  #   a.rand_pair!  #=> [:two, 2]
+  #   a             #=> {:one => 1, :three => 3}
+  #
+  def rand_pair!
+    k,v = rand_pair
+    delete( k )
+    return k,v
+  end
+  alias_method( :pick_pair, :rand_pair! )
+
+end
+
+ 

data/lib/facet/hash/collate.rb

@@ -0,0 +1,25 @@
+class Hash
+  # Returns a new hash built by iterating through each key,value 
+  # pair and updating the new hash.
+  #
+  #   require 'facet/hash/collate'
+  #
+  #   
+  #
+  #--
+  # Note that this method may get some fine tuning as it
+  # currently expects the block to return a "mini-hash"
+  # pair -- parhaps an 2-element array woud be better?
+  #++
+  def collate  # :yield:
+    newhash = {}
+    each_pair{ |k,v| newhash.update( yield(k,v) ) }
+    newhash
+  end 
+
+  # In place version of #collate.
+  def collate!(&yld)
+    replace( collate(&yld) )
+  end
+end
+

data/lib/facet/hash/collect.rb

@@ -0,0 +1,8 @@
+require 'facet/enumerable/graph'
+
+class Hash
+  # Hash#collect will return a hash rather then an array.
+  # It is simple an alias to Enumerable#graph.
+  alias_method :collect, :graph
+  alias_method :collect!, :graph!
+end

data/lib/facet/hash/each.rb

@@ -0,0 +1,28 @@
+class Hash
+  # A "smarter" hash#each which iterates through each
+  # _value_ if only one block parameter is given.
+  #
+  #   require 'facet/hash/each'
+  #
+  #   {:a=>"a", 2=>"b", "x"=>"c"}.each{ |v| puts v }
+  #
+  # _produces_
+  #
+  #   a
+  #   b
+  #   c
+  #
+  # WARNING! Use with caution. Methods from other libraries 
+  # may depend on the old behavior, expecting a two element 
+  # array to be passed into a single block argument.
+  def each(&yld)
+    case yld.arity
+    when 0
+    when 1
+      each_value{|v| yield(v)}
+    else
+      each_pair{|k,v| yld.call(k,v)}
+    end
+    self
+  end
+end

data/lib/facet/hash/has_keys?.rb

@@ -0,0 +1,48 @@
+class Hash
+  
+  #   require 'facet/hash/has_keys?'
+  #
+  #   h = { :a => 1, :b => 2 }
+  #   h.has_keys?( :a )   #=> true
+  #   h.has_keys?( :c )   #=> false
+  #
+  def has_keys?(*check_keys)
+    unknown_keys = check_keys - self.keys
+    return unknown_keys.empty?
+  end
+
+  
+  #   require 'facet/hash/has_keys?'
+  #
+  #   h = { :a => 1, :b => 2 }
+  #   h.has_only_keys?( :a, :b )   #=> true
+  #   h.has_only_keys?( :a )       #=> false
+  #  
+  def has_only_keys?(*check_keys)
+    unknown_keys = self.keys - check_keys
+    return !unknown_keys.empty?
+  end
+  
+  #   require 'facet/hash/has_keys?'
+  #
+  #   h = { :a => 1, :b => 2 }
+  #   h.assert_has_keys( :a )   #=> true
+  #   h.assert_has_keys( :c )   #=> ArgumentError
+  #
+  def assert_has_keys(*check_keys)
+    raise(ArgumentError, "does not have key(s)") unless has_all_keys?
+  end
+  
+  #   require 'facet/hash/has_keys?'
+  #
+  #   h = { :a => 1, :b => 2 }
+  #   h.assert_only_keys( :a, :b )   #=> true
+  #   h.assert_only_keys( :a )       #=> ArgumentError
+  #
+  def assert_has_only_keys(*check_keys)
+    raise(ArgumentError, "has unexpected key(s)") unless has_only_keys?
+  end
+
+end
+
+