facets 1.7.0 → 1.7.30

data/{meta/projectinfo → PROJECT}

@@ -27,12 +27,10 @@ revision:
     - doc/api        # auto-generated
     - test/lib       # ''
     - lib/facet      # ''
-    - meta/version   # should default
+    - meta/version   # should exclude by default
     - doc/ChangeLog  # so should this
 
 package:
   exclude:
-    - doc/api
-    - doc/web
     - work
 

data/README

@@ -1,29 +1,50 @@
 
 = Ruby Facets
 
-  "ALL BASE COMMON"
+  "ALL YOUR BASE ARE BELONG TO US"
 
 
 == Introduction
 
-Ruby Facets
+Ruby Facets is the a collection of general purpose, pure-Ruby extensions and additions for the Ruby programming language. Facets is divided into two libraries, one for the extensions and the other for the additions. called Facets/CORE and Facets/MORE, respectively.
 
-Facets is set of two libraries Facets/CORE and Facets/MORE.
+Facets/CORE is a large collection of methods which extend the core capabilities of Ruby's built-in classes and modules. This collection of extension methods are unique by virtue of their atomicity. The methods are stored individually so that each can be required independently. This gives developers fine-grain control over which  extra methods to bring into his or her code. The collection currently contains over 400 methods spanning 28 classes and modules. It is an _atomic_ library in that the methods are packaged individually so that each can be _required_ independently. This gives the programmer greater 
+control to include only the extra methods he or she actually needs.
 
-Facets/CORE is a vast collection of methods which extend the core
-capabilities of Ruby's built-in classes and modules.
-This collection of extension methods is unique by virtue of its atomicity.
-The methods are stored individually so that each can be required
-independently. This gives developers fine-grain control over which 
-extra methods to bring into his or her code. The collection currently 
-contains over 400 methods spanning 28 classes and modules.
+Facets/MORE are a collection of classes, modules and light frameworks whcih consitutes an ever growing and improving source of reusable components. Some very nice additions are provided, from an amazing SI Units system to an elegant Annotations system. And of course there are all the more typical goodies like Tuple, Functor and Multiton.
+
+
+== License
+
+The collection PER COLLECTION is licensed as follows:
+
+  Ruby Facets
+  Copyright (c) 2004-2006 Thomas Sawyer
+
+  Distributed under the terms of the Ruby lincense.
+
+The Ruby license is a dual license that also provides for use of the GPL.
+Complete texts of both licenses accompany this document (see doc/COPYING).
+
+  This program 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 2 of the License, or
+  (at your option) any later version.
+
+  This program 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 this program; if not, write to the Free Software
+  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+
+Acknowledgments and Copyrights for particular snippets of borrowed code
+are given in their respective source. All licenses are either compatible
+with the Ruby license (namely the GPL) or the original author has given
+permission for inclusion of their code under such lincense.</p>
 
-Facets/MORE is a collection of additioanl classes, modules and microframeworks.
-The class, module and microframework additions consitute an ever growing
-and improving source of reusable components. Some very nice additions
-are available, from an amazing Units system to an elegant
-annotations systems. And of course there are all the more typical goodies
-like Tuple, Functor and Multiton.
 
 == Mission
 
@@ -60,14 +81,29 @@ setup.rb script. For example:
 == Usage
 
 For detailed usage of any given method or module please refer to the
-API RDocs. Most are well documented.
+API RDocs. Most are well documented. Assistance in improving 
+documentation though is always appreciated.
+
+The general require statement for an atomic facet extension is as follows: 
+
+  require 'facet/<class|module>/<method-name>'
 
-To use a single CORE facet you simply require the method by name, for example:
+For example:
 
   require 'facet/time/stamp'
 
-Techinally this requires a redirection file to the core method itself.
-Redirection can be bypassed. Eg.
+Teh path is alwasy lower. The name may differ a bit from the actual
+method being required. For instance, if the name ends in ?, !, or = the
+character is simply removed. For method names that are non-alphanumeric
+althogether, a name is chosen according to the chracters and
+prefixed with 'op_' for "operator" (see chart below).
+
+Most "atoms" contain but a single method, but excpetions occur when methods
+are very tightly related. In these case "stubs" are used to have one required
+method require the group.
+
+The use of "facet/" namespace techinally uses a redirection file to file in 
+facets/core. Redirection can be bypassed however:
 
   require 'facets/core/time/stamp'
 
@@ -79,7 +115,7 @@ requiring any of them you first require the main facility.
 
   require 'facets'
 
-This loads a set of facets considered "base" --currently a couple dozen
+This loads a set of facets considered "BASE" --currently a couple dozen
 very basic methods, and adds the facets library directories to the end
 of Ruby's load path. This allows you to require facets without even using
 the 'facet/...' prefix. Eg.
@@ -122,10 +158,60 @@ prefixless shorcut to require it.
 
 For details pertaining to the functionality of each feature, please see the API Docs.
 
-
-== Notes
-
-=== Directories
+== Important Considerations for certain Facets
+
+Some caution should be taken when using certain facets.
+What follows ois list of such facets and the reasons
+these particular facets should given special consideration.
+
+Some facets require other files to be loaded first
+that are not loaded automatically, like fileutils
+(i.e. they are part of the standard lib, not core).
+The file include all of the following.
+
+  date/*
+  fileutils/*
+  ostruct/*
+  logger/*
+  gem/*
+
+Others effect the system in slightly non-standard ways.
+Though such changes are kept to a minumim and intended
+to be backward compatible, there still may be edge cases
+that could cause another library to misbehave. 
+The following is a list known facets that may have 
+this potential.
+
+  array/op_fetch.rb
+  array/op_store.rb
+  binding/self/of_caller.rb
+  hash/op_fetch.rb
+  hash/op_store.rb
+  numeric/succ.rb
+  numeric/pred.rb
+  string/succ.rb
+  string/unpack.rb
+  module/attr.rb
+
+There are also some facets that are potentially unsafe b/c
+they change Ruby's default behavior in a nonconvential
+manner and hence are not designed to be backward compatible.
+Using these with a pre-existent program may cause the program
+to misbehave. So while they can be useful, be sure to 
+understand exactly what they do before putting them to 
+ serious use.
+
+  hash/each.rb
+  module/methods.rb
+  object/method.rb
+  nilclass/op_fetch.rb
+  nilclass/empty.rb
+  nilclass/include.rb
+  nilclass/size.rb
+  nilclass/length.rb
+  nilclass/method_missing.rb
+
+== Facets' Directory Layout
 
 There are two subdirectories in Facets library, 'core', which stores
 the method extensions and 'more' which store the modules, classes and
@@ -141,7 +227,7 @@ Class method are stored in the same manner but under a 'self' subdirectory.
 
   'core/<class|module>/self/<method-name>'
 
-=== Method File Names
+== Method File Names
 
 Operators are stored in the file system using english names. For instance for
 Proc#* is 'proc/op_mul'.
@@ -182,7 +268,7 @@ simply removed.
 
 This project thrives on contribution.
 
-If you have any extension methods, classes, modules or microframeworks
+If you have any extension methods, classes, modules or small frameworks
 that you think have general applicability and would like to see them 
 included in this project, don't hesitiate to submit. There's a very good
 chance it will be included.  Also, if you have better versions of any thing
@@ -218,27 +304,9 @@ If anyone is missing from the list, please let me know and
 I will correct right away. Thanks.
 
 
-== License
-
-In so far as it matters, the collection PER COLLECTION is licensed
-as follows:
-
-  Ruby Facets
-  Copyright (c) 2004-2006 Thomas Sawyer
-  Ruby License
-
-The Ruby license is a dual license that also provides for use of the GPL.
-A copy of both licenses accompany this document (see COPYING).
-
-Credit and Copyrights for particular borrowed code segments are
-given in their respective source. All licenses are either compatible
-with the Ruby license (namely the GPL) or the original author has given
-permission for inclusion of their code under such lincense.</p>
-
-
 == Pitch
 
-  ALL YOUR BASE ARE BELONG TO RUBY
+  ALL YOUR BASE ARE BELONG TO RUBY!
 
 
 ----
@@ -252,7 +320,6 @@ permission for inclusion of their code under such lincense.</p>
     Finally let's not forget even older "working" titles that were used
     along the way: Raspberry, ABC, Succ and the very original Tomslib.
 
-
 # Copyright (c)2006 Thomas Sawyer
 # facets.rubyforge.com
 # (ruby-lang.org) Do you Ruby?

data/VERSION

@@ -0,0 +1 @@
+1.7.30 beta (2006-08-23)

data/doc/{ChangeLog → CHANGELOG}

@@ -1,3 +1,33 @@
+  * moved File.bitbucket to File.null (but bitbucket was so "fun"! ;)
+  * added nilclass/to_path
+  * added kernel/load_local
+  * added kernel/callee
+  * added enumerable/eachn, integer/each and integer/of
+  * re-added array/delete_values_at
+  * added filetest/self/root
+  * added cache.rb
+  * moved Dir.bitbucket to File.bitbucket
+  * removed task file in favor of sake based util/
+  * added main_as_module
+  * added doublemetaphone (Thanks Lawrence Philps!)
+  * rewrote taskable.rb
+  * minor doc fix to association.rb
+  * added symbol/to_s which caches the result for speed up
+  * additions and adjusments related to hash/delete_at
+  * added Dir.bitbucket
+  * update to array/op_fetch to include op_store
+  * updated docs and util tasks
+  * ice
+  * minor changes
+  * added filesystem.rb
+  * taskable should now work at the toplevel too
+  * still working the organization as Reap/Sake change
+  * started setting project tasks up for sake
+  * updates to enumerable each_slice
+  * updated names of meta files
+  * updates to READMEs
+  * added trace to command.rb
+  * organizational changes
  1.7
   * fix to inifinty.rb
   * comment on cut.rb needed a quick fix

data/lib/facet/cache.rb

@@ -0,0 +1 @@
+require 'facets/more/cache.rb'

data/lib/facet/doublemetaphone.rb

@@ -0,0 +1 @@
+require 'facets/more/doublemetaphone.rb'

data/lib/facet/enumerable/eachn.rb

@@ -0,0 +1 @@
+require 'facets/core/enumerable/eachn.rb'

data/lib/facet/file/self/null.rb

@@ -0,0 +1 @@
+require 'facets/core/file/self/null.rb'

data/lib/facet/filesystem.rb

@@ -0,0 +1 @@
+require 'facets/more/filesystem.rb'

data/lib/facet/filetest/self/root.rb

@@ -0,0 +1 @@
+require 'facets/core/filetest/self/root.rb'

data/lib/facet/hash/delete_at.rb

@@ -0,0 +1 @@
+require 'facets/core/hash/delete_at.rb'

data/lib/facet/hash/delete_values.rb

@@ -0,0 +1 @@
+require 'facets/core/hash/delete_values.rb'

data/lib/facet/hash/delete_values_at.rb

@@ -0,0 +1 @@
+require 'facets/core/hash/delete_values_at.rb'

data/lib/facet/kernel/load_local.rb

@@ -0,0 +1 @@
+require 'facets/core/kernel/load_local.rb'

data/lib/facet/main_as_module.rb

@@ -0,0 +1 @@
+require 'facets/more/main_as_module.rb'

data/lib/facet/nilclass/to_path.rb

@@ -0,0 +1 @@
+require 'facets/core/nilclass/to_path.rb'

data/lib/facet/symbol/to_s.rb

@@ -0,0 +1 @@
+require 'facets/core/symbol/to_s.rb'

data/lib/facets.rb

@@ -68,6 +68,7 @@ require 'facets/core/kernel/constant'
 require 'facets/core/kernel/__callee__'  # better name?
 require 'facets/core/kernel/__method__'
 require 'facets/core/symbol/to_proc'
+require 'facets/core/symbol/to_s'
 
 # Elementary (Know Thyself)
 require 'facets/core/hash/to_h'

data/lib/facets/core/array/delete_values_at.rb

@@ -11,6 +11,7 @@ class Array
   #   a.delete_values_at(0..2)  #=> [1,2,3]
   #   a                         #=> [4]
   #
+
   def delete_values_at(*selectors)
     idx = []
     selectors.each{ |i|
@@ -55,3 +56,4 @@ end
   end
 
 =end
+

data/lib/facets/core/array/op_fetch.rb

@@ -1,3 +1,4 @@
+require 'facets/core/array/store'
 
 class Array
 
@@ -15,9 +16,27 @@ class Array
     return slice(*args)
   end
 
+  # Modifies #[]= to accept an array of indexes for assignment.
+  #
+  #   a = ['a','b','c','d']
+  #
+  #   a[[1,-1]] = ['m','n']    #=> ['m','n']
+  #   a                        #=> ['a','m','c','n']
+  #
+  def []=(*args)
+    if Array === args.at(0)
+      idx,vals = args.at(0),args.at(1)
+      idx.each_with_index{ |a,i| store(a,vals.at(i)) }
+      return values_at( *idx )
+    else
+      return store(*args)
+    end
+  end
+
 end
 
 
+
 #  _____         _
 # |_   _|__  ___| |_
 #   | |/ _ \/ __| __|
@@ -35,6 +54,14 @@ end
       assert_equal( ['b','f'], a[[1,-1]] )
     end
 
+    def test_op_store
+      a = ['a','o','z']
+      a[[0,2]] = ['A','Z']
+      assert_equal( ['A','o','Z'], a )
+      a[[0,-1]] = ['W','Y']
+      assert_equal( ['W','o','Y'], a )
+    end
+
   end
 
 =end

data/lib/facets/core/array/op_store.rb

@@ -1,47 +1,2 @@
-require 'facet/array/store'
-
-class Array
-
-  # Modifies #[]= to accept an array of indexes for assignment.
-  #
-  #   a = ['a','b','c','d']
-  #
-  #   a[[1,-1]] = ['m','n']    #=> ['m','n']
-  #   a                        #=> ['a','m','c','n']
-  #
-  def []=(*args)
-    if Array === args.at(0)
-      idx,vals = args.at(0),args.at(1)
-      idx.each_with_index{ |a,i| store(a,vals.at(i)) }
-      return values_at( *idx )
-    else
-      return store(*args)
-    end
-  end
-
-end
-
-
-#  _____         _
-# |_   _|__  ___| |_
-#   | |/ _ \/ __| __|
-#   | |  __/\__ \ |_
-#   |_|\___||___/\__|
-#
-=begin test
-
-  require 'test/unit'
-
-  class TCArray < Test::Unit::TestCase
-
-    def test_op_stroe
-      a = ['a','o','z']
-      a[[0,2]] = ['A','Z']
-      assert_equal( ['A','o','Z'], a )
-      a[[0,-1]] = ['W','Y']
-      assert_equal( ['W','o','Y'], a )
-    end
-
-  end
-
-=end
+#stub
+require 'facets/core/array/op_fetch.rb'

data/lib/facets/core/enumerable/each_by.rb

@@ -1,2 +1,91 @@
-# stub
-require 'facet/enumerable/each_slice'
+require 'enumerator'
+
+module Enumerable
+
+  # Iterate through slices. If slicing +step+ is not
+  # given, the the arity if the block is used.
+  #
+  #   x = []
+  #   [1,2,3,4].each_by{ |a,b| x << [a,b] }
+  #   x  #=> [ [1,2], [3,4] ]
+  #
+  #   x = []
+  #   [1,2,3,4,5,6].each_by(3){ |a| x << a }
+  #   x  #=> [ [1,2,3], [4,5,6] ]
+
+  def each_by(step=nil, &yld)
+    if step
+      each_slice(step,&yld)
+    else
+      step = yld.arity.abs
+      each_slice(step,&yld)
+    end
+  end
+
+end
+
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+=begin test
+
+  require 'test/unit'
+
+  class TCEnumerable < Test::Unit::TestCase
+
+    def test_01
+      x = []
+      [1,2,3,4].each_by{ |a,b| x << [a,b] }
+      o = [[1,2],[3,4]]
+      assert_equal( o, x )
+    end
+
+    def test_02
+      x = []
+      [1,2,3,4,5].each_by{ |a,b,c| x << [a,b,c] }
+      o = [[1,2,3],[4,5,nil]]
+      assert_equal( o, x )
+    end
+
+    def test_03
+      x = []
+      [1,2,3,4].each_by(2){ |a,b| x << [a,b] }
+      o = [[1,2],[3,4]]
+      assert_equal( o, x )
+    end
+
+    def test_04
+      x = []
+      [1,2,3,4,5,6,7,8].each_by(4){ |*a| x << a }
+      o = [ [[1,2,3,4]],[[5,6,7,8]] ]
+      assert_equal( o, x )
+    end
+
+    def test_05
+      x = []
+      [1,2,3,4,5,6].each_by(3){ |*a| x << a }
+      o = [ [[1,2,3]],[[4,5,6]] ]
+      assert_equal( o, x )
+    end
+
+    def test_06
+      a = [1,2,3,4,5,6]
+      r = []
+      a.each_by(2){ |x,y| r << [x,y] }
+      assert_equal( [[1,2],[3,4],[5,6]], r )
+    end
+
+    def test_07
+      a = [1,2,3,4,5,6]
+      r = []
+      a.each_by(3){ |*e| r << e }
+      assert_equal( [ [[1,2,3]], [[4,5,6]] ], r )
+    end
+
+  end
+
+=end