facets 1.1.0 → 1.2.0

data/AUTHORS

@@ -14,20 +14,23 @@
 * Michael Granger
 * Florian Gross
 * Thomas-Ivo Heinen
+* David H. H.
 * Ara T. Howard
 * Mohammad Khan
 * Derek Lewis
+* Jan Molic
 * George Moschovitis
 * Michael Neumann
-* Jan Molic
+* Jonas Pfenniger
 * Thomas Sawyer
 * Daniel Schierbeck
 * Gavin Sinclair
 * Tilo Sloboda
 * Peter Vanbroekhoven
 * Jim Weirich
+* Jeff Wood
 * Austin Ziegler
 * why_the_lucky_stiff
 
-If there are any manes missing from this list, please let me know
+If any names are missing from this list, please let me know
 and I will correct immediately.

data/ProjectInfo

@@ -1,8 +1,8 @@
---- %YAML:1.0
+---
 
 TITLE    : Facets
 NAME     : facets
-VERSION  : '1.1.0'
+VERSION  : '1.2.0'
 DATE     : '2006-03-10'
 STATUS   : Beta/Stable
 
@@ -13,11 +13,14 @@ HOMEPAGE : "http://facets.rubyforge.org"
 SUMMARY: Vast collection of atomic core extension methods.
 
 DESCRIPTION: >
-  Facets Core is a large collection of core extension methods for
-  the Ruby programming language. The extensions are unique by virtue
-  of thier atomicity. Methods are stored in their own files,
+  Facets Core is a large collection of core extension methods
+  and module additions for the Ruby programming language.
+  The extensions are unique by virtue of thier atomicity.
+  Methods are stored in their own files,
   allowing for highly granular control of requirements, for
   this reason I like to call it Ruby's Atomic Library.
+  The modules include a number of useful classes, mixins and
+  microframeworks.
 
 DISTRIBUTE: [ gem, tar.bz2 ]
 
@@ -27,19 +30,25 @@ PACKAGE:
     - dist
     - dev
     - web
-    - notes
+    - note
 
 RUBYFORGE:
   PROJECT: 'facets'
   USERNAME: transami
 
 RDOC:
-  dir: web/doc/api
-  template: jamis
-  options: ['--all', '--inline-source']
-  include:
-    - 'lib/facet/**/*'
-    - '[A-Z]*'
+  - dir: web/doc/api/core
+    template: jamis
+    options: ['--all', '--inline-source']
+    include:
+      - 'lib/facets/core/**/*'
+      - '[A-Z]*'
+  - dir: web/doc/api/more
+    template: jamis
+    options: ['--all', '--inline-source']
+    include:
+      - 'lib/facets/more/**/*'
+      - '[A-Z]*'
 
 PUBLISH:
   host: rubyforge.org

data/README

@@ -6,7 +6,9 @@
 
 == Introduction
 
-Ruby Facets is a vast collection of methods which extend the core
+Ruby Facets
+
+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.
@@ -15,6 +17,16 @@ 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 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 adsitions
+have recently been added, 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
+
 Facets holds to the notion that the more we can reasonably integrate into
 a common foundation directed toward general needs, the better that foundation 
 will be able to serve us. There are a number of advantages here:
@@ -51,47 +63,67 @@ setup.rb script. For example:
 For detailed usage of any given method or module please refer to the
 API RDocs. Most are well documented.
 
-To use a facet you simply require the method by name, for example:
+To use a single facet you simply require the method by name, for example:
 
   require 'facet/time/stamp'
 
-Although not neccessary it is recommended that before requiring
-any other facet you first require the main facility.
+Techinally this requires a redirection file to the core method itself.
+You can bypass the redirection:
+
+  require 'facets/core/time/stamp'
+
+Although not at all neccessary, if you are using more then a few facets
+it is recommended that before requiring any of them you first require
+the main facility.
 
   require 'facets'
 
-This loads all the core facets considered "base" (a couple dozen common methods)
-and the Facets system module. The Facets module provides meta information about
-the facets available.
+This loads all the core facets considered "base" (a couple dozen basic methods)
+and add the facets library directories to the end of Ruby's load path. This
+allows you to require facets without the 'facet/...' prefix. Eg.
+
+  require 'string/blank'
 
-Some extension method sets are also available. For example:
+A handful of extension sets are also available. For example,
 
   require 'facet/string_as_array'
 
-The most extensive of these is 'all'. The 'all' set requires nearly every
-Facets extension method there is. The only methods NOT required are those
-considered "cautionary" in the way they effect Ruby b/c they may potentially
-disrupt pre-existing code. Note that 'all' is not the recommended way to 
-use Facets and is only provided with a priviso of caution --that's alot
-of methods!
+adds some methods to Array that make it behave a little more like
+an array of characters. Other useful sets include, 'random' which 
+loads every facet method related to randomness and 'inflect' which
+loads a number of methods for manipulating strings in high-level
+ways, like #camelize and #pluralize.
+
+Using a module, class or microframework is essentially the same. 
+You can use the redirection path. Eg.
+
+  require 'facet/basicobject'
 
-More useful sets include, 'random' which loads every facet method related to
-randomness and 'inflect' which loads a number of methods for manipulating
-strings in high-level ways, like #camelize and #pluralize.
+Or do so directly.
 
-Please see the API Docs for details pertaining to the functionality
-of each feature.
+  require 'facets/more/basicobject'
+
+Again, if you load the main facility, you can eliminate the need for the 'facet/' prefix.
+
+  require 'facets'
+  require 'basicobject'
+
+Understand that on the off chance that anoth library you are using has the same name as 
+one of Facets' everything will still work fine. You will not be able to use the
+prefixless shorcut to require the facet.
+
+For details pertaining to the functionality of each feature, please see the API Docs.
 
 
 == Notes
 
 === Directories
 
-There are presently three subdirs in Facets: 'nano', which stores
-the method extensions, 'mega' which store the modules, classes and
-micorframeworks, and 'unit' which stores development utilities.
+There are presently three two subdirs in Facets: 'core', which stores
+the method extensions and 'more' which store the modules, classes and
+micorframeworks.
 
-The layout of Facets' method files is straightfoward and well organized.
+The layout of Facets' core method files is straightfoward and well organized.
 All individual methods are stored in subdirectories under their effected 
 downcased class' or module's name.
 
@@ -99,7 +131,7 @@ downcased class' or module's name.
 
 Class method are stored in the same manner but under a 'self' subdirectory.
 
-  '<class|module>/self/<method-name>'
+  'core/<class|module>/self/<method-name>'
 
 === Method File Names
 
@@ -180,25 +212,22 @@ I will correct right away. Thanks.
 
 == License
 
-In so far as it matters, the collection PER COLLECTION is licensed 
+In so far as it matters, the collection PER COLLECTION is licensed
 as follows:
 
   Ruby Facets
-  Copyright (c) 2004,2005 Thomas Sawyer
+  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).
 
-Fortunately nearly all the code is copyrighted under the same open license,
-namely the Ruby License. But some of the code is licensed differently 
-according to the original authors wishes. In the few excpetions I have
-included the copyright notice with the source code. All such licesnses are
-OOS licesnes. I am in the proccess of asking the particular authors to consider
-allowing the use of the single Ruby license so that one license can 
-serve for all. (UPDATE: Not very much left under seperate licenses.)
+Credit and Copyrights for particular borrowed code segments are
+given in their respective source. All licenses are either compatible
+with the Ruby lincense (Ruby or GPL) or the original author has given
+permission for inclusion of their code under this lincense.</p>
 
-Any code file not specifically labelled shall fall under the Ruby License.
+Any code file not specifically labeled shall fall under the Ruby License.
 
 
 == Pitch
@@ -209,15 +238,15 @@ Any code file not specifically labelled shall fall under the Ruby License.
 ----
 
 [1] A lot of mental anguish went into finding this good project name Ruby Facets.
-    Of course, in the end only one name can take the honor. Other good names which were 
-    considered: Warchest w/ Atomix, Downs & Ace, Trix & Atomx and even Pillbox & Pills
-    (a _why suggestion).  Then the names that almost won out and were used for a good while:
-    Nano Methods and Mega Modules --great names but turned maybe a little to "fad".
-    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)2005 Thomas Sawyer 
-# --.com : The web page without a name.
-# (ruby-lang.org) Do you Ruby?
+    Of course, in the end only one name can take the honor. Other good names
+    which were considered: Calibre, Florida and California, Warchest w/ Atomix,
+    Downs & Ace, Trix & Atomx and even Pillbox & Pills (a _why suggestion).
+    Then the names that almost won out and were used for a good while:
+    Nano Methods and Mega Modules --great names but a little to "fad".
+    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/Rakefile

@@ -6,24 +6,25 @@
 require 'yaml'
 require 'fileutils'
 
-require './lib/facet/file/self/read_list'
+require './lib/facets/core/file/self/read_list'
+
+#VERSION = "1.2.0"
 
-#VERSION = "2005-11-05"
-REQPATH = "facet"
 DATPATH = "data/facets"
 ETCPATH = "conf/facets"
-MTHPATH = "lib/facet"
-GENPATH = "lib/facet"
+REQPATH = "facets/core"
+MTHPATH = "lib/facets/core"
+GENPATH = "lib/facets/core"
+
 
 #-----------------------------------------------------
 # Generate facet/
 #-----------------------------------------------------
-=begin
 desc %{Build facet redirect directory}
-task :facet do
-  sh %{rm -R './lib/facet'}
-  ['ext','set/special','set/general'].each{ |d|
-    from = "lib/facets/2005-11-05"
+task :redirect do
+  sh %{rm -R 'lib/facet'} if File.directory?('lib/facet')
+  ['core','more'].each{ |d|
+    from = "lib/facets"
     rbs = Dir.glob( File.join( from, d, '**/*.rb' ) )
     rbs.each { |e|
       nolib = e.gsub( /^lib\//, '' )
@@ -36,7 +37,6 @@ task :facet do
     }
   }
 end
-=end
 
 #-----------------------------------------------------
 # Read in the facets directory and sort-out per class

data/data/facets/index.yml

@@ -413,6 +413,7 @@ string:
 - self/rand_letter
 - self/random
 - shatter
+- shell_escape
 - shift
 - shuffle
 - similarity

data/lib/facet/annotation.rb

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

data/lib/facet/ansicode.rb

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

data/lib/facet/array.rb

@@ -1,34 +1 @@
-require 'facet/array/at_rand'
-require 'facet/array/body'
-require 'facet/array/delete_unless'
-require 'facet/array/delete_values'
-require 'facet/array/delete_values_at'
-require 'facet/array/each_with_key'
-require 'facet/array/first'
-require 'facet/array/foot'
-require 'facet/array/head'
-require 'facet/array/last'
-require 'facet/array/last_index'
-require 'facet/array/merge'
-require 'facet/array/mid'
-require 'facet/array/middle'
-require 'facet/array/op_fetch'
-require 'facet/array/op_mod'
-require 'facet/array/op_store'
-require 'facet/array/pick'
-require 'facet/array/pos'
-require 'facet/array/pull'
-require 'facet/array/rand_index'
-require 'facet/array/rand_subset'
-require 'facet/array/range'
-require 'facet/array/rotate'
-require 'facet/array/select'
-require 'facet/array/shuffle'
-require 'facet/array/slap'
-require 'facet/array/store'
-require 'facet/array/tail'
-require 'facet/array/thru'
-require 'facet/array/to_b'
-require 'facet/array/to_h'
-require 'facet/array/to_hash'
-require 'facet/array/unzip'
+require 'facets/core/array.rb'

data/lib/facet/array/at_rand.rb

@@ -1,52 +1 @@
-class Array
-
-  # Return a random element of the array.
-  #
-  #   [1, 2, 3, 4].at_rand           #=> 2
-  #   [1, 2, 3, 4].at_rand           #=> 4
-  #
-  def at_rand
-    self.at( rand( size ) )
-  end
-
-  # Same as #at_rand, but acts in place removing a
-  # random element from the array.
-  #
-  #   a = [1,2,3,4]
-  #   a.at_rand!       #=> 2
-  #   a                #=> [1,3,4]
-  #
-  def at_rand!
-    return delete_at( Kernel.rand( size ) )
-  end
-
-end
-
-
-#  _____         _
-# |_   _|__  ___| |_
-#   | |/ _ \/ __| __|
-#   | |  __/\__ \ |_
-#   |_|\___||___/\__|
-#
-=begin test
-
-  require 'test/unit'
-
-  class TCArray < Test::Unit::TestCase
-
-    def test_at_rand
-      a = [1,2,3,4,5]
-      20.times{ assert_nothing_raised{ a.at_rand } }
-      20.times{ assert( a.include?( a.at_rand ) ) }
-    end
-
-    def test_at_rand!
-      a = ['a','b','c']
-      assert_equal( 1, a.at_rand!.length )
-      assert_equal( 2, a.length )
-    end
-
-  end
-
-=end
+require 'facets/core/array/at_rand.rb'

data/lib/facet/array/body.rb

@@ -1,2 +1 @@
-# stub
-require 'facet/array/head.rb'
+require 'facets/core/array/body.rb'

data/lib/facet/array/delete_unless.rb

@@ -1,35 +1 @@
-#--
-# Daniel Schierbeck
-#++
-
-class Array
-
-  def delete_unless (&block)
-    delete_if { |element| not block.call(element) }
-  end
-
-end
-
-
-
-#  _____         _
-# |_   _|__  ___| |_
-#   | |/ _ \/ __| __|
-#   | |  __/\__ \ |_
-#   |_|\___||___/\__|
-#
-=begin test
-
-  require 'test/unit'
-
-  class TC_DELETE_UNLESS < Test::Unit::TestCase
-
-    def test_delete_unless
-      a = [1,2,3]
-      a.delete_unless{ |e| e == 2 }
-      assert_equal( [2], a )
-    end
-
-  end
-
-=end
+require 'facets/core/array/delete_unless.rb'