facets 0.7.2 → 0.9.0

data/LICENSE/LICENSE-MIT

@@ -0,0 +1,8 @@
+The MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ 

data/LICENSE/LICENSE-RUBY

@@ -0,0 +1,60 @@
+The Ruby License (http://www.ruby-lang.org/en/LICENSE.txt)
+----------------------------------------------------------
+
+You may redistribute this software and/or modify it under either the terms of
+the GPL (see the file GPL), or the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+          modifications to Usenet or an equivalent medium, or by allowing
+          the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) rename any non-standard executables so the names do not conflict
+          with standard executables, which must also be provided.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or executable
+     form, provided that you do at least ONE of the following:
+
+       a) distribute the executables and library files of the software,
+          together with instructions (in the manual page or equivalent)
+          on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+          the software.
+
+       c) give non-standard executables non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).  But some files in the distribution
+     are not written by the author, so that they are not under these terms.
+
+     For the list of those files and their copying conditions, see the
+     file LEGAL.
+
+  5. The scripts and library files supplied as input to or produced as
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them,
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.
+
+  

data/ProjectInfo

@@ -0,0 +1,71 @@
+--- %YAML:1.0
+
+TITLE    : &title Ruby Facets
+NAME     : &pkg facets
+VERSION  : '0.9.0'
+DATE     : '2005-10-30'
+STATUS   : Beta/Stable
+
+AUTHOR   : Thomas Sawyer
+EMAIL    : &email transfire@gmail.com
+HOMEPAGE : "http://facets.rubyforge.org"
+
+SUMMARY: The proverbial Zoo-of-More for Ruby
+
+DESCRIPTION: >
+  Ruby Facets is a cornicopia of extension methods and module,
+  class and microframework additions for the Ruby programming
+  language. The extensions, known as the Nano Methods, or the
+  Atomic Library, is unique by virtue of thier atomicity. 
+  Methods are stored in their own files, allowing for highly
+  granular control of requirements.
+
+DISTRIBUTE: [ gem, tar.bz2, zip ]
+
+PACKAGE:
+  exclude:
+    - dev
+
+RUBYFORGE:
+  PROJECT: 'facets'
+  USERNAME: transami
+
+#TEST:
+#  fixture: 'facets'
+
+RDOC:
+  - dir: web/rdoc-nano
+    template: jamis
+    options: ['--all', '--inline-source']
+    include:
+      - 'lib/nano/**/*'
+      - '[A-Z]*'
+  - dir: web/rdoc-mega
+    template: jamis
+    options: ['--all', '--inline-source']
+    include:
+      - 'lib/mega/**/*'
+      - '[A-Z]*'
+
+PUBLISH:
+  -
+    host: rubyforge
+    type: web
+    username: transami
+    project: facets
+    dir: 'web'
+
+ANNOUNCE:
+  to: transfire@gmail.com #ruby-talk@ruby-lang.org
+  from: transfire@gmail.com
+  domain: jupiterzeus.net
+  server: smtp.gmail.com
+  port: 25 #587
+  account: transfire@gmail.com
+  authtype: login  #cram_md5 #plain
+  sectype: tls # ~, tls, ssl
+  file: ANN
+  slogan: ALL YOUR BASE ARE BELONG TO RUBY!
+  links:
+    - http://facets.rubyforge.org
+

data/README

@@ -1,176 +1,204 @@
 
 = Ruby Facets
 
-== What is this?
+  "ALL BASE COMMON"
 
-Ruby Facets is the a collection of general, pure-Ruby extensions
-and additions for the Ruby programming language. The extensions are known
-as the Atomic Methods, design falls into
-two parts: the Atomic Methods and the CMMs (Classes, Modules and Mixins).
 
-=== The Atomic Library
+== Introduction
 
-The heart of Ruby Facets, which truth be told stands for Fantastic Atomic Core Extensions,
-is an growing collection of methods to complement Ruby's core and standard
-libs. 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.
-The package currently contains over 300 atomic methods, spanning over 26 classes and modules.
+Ruby Facets is a vast collection of methods which extend the core
+capabilities of Ruby's built-in classes and modules PLUS a large
+collection of additional modules, classes and microframeworks.
+The goal of the project is to offer large set of high-quality
+programming "parts" that target a variety of usecases.
 
-=== The Classes, Modules and Mixins
+The collection of extension methods is unique by virtue of its atomicity. 
+Tthe 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.
 
-In addition to the atomic methods, Facets also includes a large collection 
-of addon classes, modules and mixins. [Note: These used to reside in a separate lib
-called Carats. This has been deprecated in favor of a single package.]
+The class, module and microframework additions consitute an ever growing
+and improving source of reusable components. Some very nice addations
+havve 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.
 
-In short, through a single package, the Ruby programmer is treated to a
-plethora of programming tools.
+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:
 
+    * Better Code-reuse
+    * Collaborative Improvements
+    * Greater Name Consistency
+    * One-stop Shop and Installation
 
-== Calibre
 
-Ruby Facets is part of the Calibre project. You can learn more at:
+== Status
 
-  http://calibre.rubyforge.com
+The current status is quite good. While various parts are still considered
+Beta, everything should be relatively usable.
 
 
 == Installation
 
+
 The easiest way to install is via RubyGems. On the command line enter:
 
   > gem install facets
 
-To manually install, untar the package and use the included setup.rb script.
-For example:
-  
-  > tar -xvzf facets-x.y.z.tar.gz
-  > cd facets--x.y.z
+To manually install, unpack the .tbz (.tar.bz2) package and use the included
+setup.rb script. For example:
+
+  > tar -xvzf facets,YYYY-MM-DD.tbz
+  > cd facets,YYYY-MM-DD
   > sudo ruby setup.rb
 
 
 == Usage
 
-There are quite a few methods, classes and modules. For detailed usage it is best
-to refer to the API RDocs. Most is well documented. Assistance in 
-improving documentation though is always appreciated.
+For detailed usage of any given method or module please refer to the
+API RDocs. Most are well documented.
 
-The general require statement for an atomic facet is as follows: 
+Although not at all neccessary it is recommended that before requiring
+any other facet you first require the main facility.
 
-  require 'facet/<class|module>/<method-name>'
+  require 'facets'
 
-All lowercase. The method-name may differ a bit from the actual method. If a method-name
-ends in ?, !, or = the character is simply removed. For methods that are non-alphanumeric,
-a suitable name is chosen according ot the methods functionaity and then suffixed with '-op',
-for "operator". For example, perhaps a paricular application would be better
-served if the NilClass responded to the <tt>#empty?</tt> message.
-  
-  require 'facet/nil/empty'
+This loads all the facets considered "base" --facets that are fundementally
+useful, plus loads the Facets system module. The Facets module provides a
+more robust interface to aquiring extension methods. In the past one would
+have used the Kernel#require method like so:
 
-And the <tt>#empty?</tt> method will then be only new method added.
-Most "atoms" contain but a single method, but excpetions occur when methods
-very tightly related. 
+  require 'facet/time/stamp'  # TOO BE DEPRECATED !!!
 
-There are also numerous shortcuts for including atoms in mass.
-Some of these occur at the top-level under 'facets/', while
-others occur in the atomic subdirectory 'facets/{class|module}/'.
+You should begin transitioning to:
 
-The two most notable shortcuts are 'base' and 'common'.
-If you wish to include all the methods considered basic:
+  Time.use Facets, :stamp
 
-  require 'facet/base'
+Using this method allows Facets to work more perceisely and efficiently. One 
+of the advantages that arises is that Facets' can search the class hierarchy
+for a method. For example if you wanted to use #each_permutation on an Array.
 
-This represents a group of about two dozen methods that are 
-considered likely to be included in future versions of Ruby itself.
-If you would like to include the "base" methods plus all the methods
-considered "common":
+  Array.use Facets, :each_permutation
 
-  require 'facet/common'
+Even though #each_permutation is a method of Enumerable this will still work
+because Enumerable is a superclass of Array.
 
-This is a large selection of methods that are considered the most 
-often useful.
+Also it allows for the use operators without special recourse.
+For instance, the Proc compostion operator can be require simply.
 
-All methods considered "uncommon" must be require individually.
-It is possible for a few of the uncommon methods to conflict,
-so there is no way to include _everything_ all at once.
+  Proc.use Facets, :*
 
-On top of all this there are the non-atomic additions. These never
-fall into a subdirectory, and can always be require accordingly:
+If you're wondering why you have to specify the Facets module in #use,
+it is becuase #use is a generalized method. Anyone can easily take advantage
+of this functionality by utlizing Facets' Module-Package system (package.rb).
+See the API Documentation for further details of putting this to use in your
+programs.
 
-  require 'facet/{file-name}'
+Some extension methodsets are also available. These are loaded in traditional
+manner. For example:
 
-As for actual examples, well that might require a book.
-But again, refer to the API docs.
+  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!
 
-== Contribute
+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.
+
+The rest of Facets, the modules, classses and microframeworks are
+requirable through the traditional interface as well. For example:
 
-The project thrives on contribution. Please feel free to offer any
-extension you wish. The criteria for inclusion is fairly light:
+  require 'facet/units'
 
-* Is it generally useful and/or highly interesting? 
-* Does it pass a basic testcase?
+Facets also includes an alternative way to use classes and modules.
+By calling the #autorequire method, Facets will automatically
+require the appropriate files when you first attempt to use one. 
+For example:
+
+  require 'facets'
+
+  Facets.autorequire
+  
+  t = Tuple[1,2,3]
 
-If it meets these requirements then it will in all likelihood 
-be accepted into the main facets lib. 
+And the 'tuple.rb' file will be automatically required. The auto-requiring
+also handily applies to some of Ruby's standard library. 
+Keep in mind though that the microframeworks do not generally work with this,
+since they are not typical bound to a particular module or class, 
+so those will have to be required on their own.
+
+Please see the API Docs for details pertaining to the functionality
+of each feature.
+
+
+== Contribute
+
+This project thrives on contribution. 
+
+If you have any extension methods, classes, modules or microframeworks
+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
+already included or simply have a patch, they too are more than welcome.
+We want Ruby Facets to be of the highest quality.
 
 
 == Authorship
 
 This collection was put together by, and largely written by Thomas Sawyer
-(aka T. Onoma). He can be reached via email at transfire at gmail.com.
+(aka Trans Onoma). He can be reached via email at transfire at gmail.com.
 
 Some parts of this collection were written and/or inspired by other
 persons. Fortunately nearly all were copyrighted under the same open
-license as this library. In the few excpetions I have included the
-copyright notice with the source code. In all cases, I have made every
-effort to give credit where credit is due. You will find these thanks
-and acknowledgements at the beginning of the source code.
+license, the Ruby License. In the few excpetions I have included the
+copyright notice with the source code. 
+
+Any code file not specifically labelled shall fall under the Ruby License.
+
+In all cases, I have made every effort to give credit where credit is due. You will find these copyrights, thanks and acknowledgements embedded in the source code, and an unobtrusive
+"Author(s)" section is given in the RDocs.
+
+Main Developers include:
 
 * Thomas Sawyer
-* Paul Brannan
-* Renald Buter
-* Hal Fulton
-* Gavin Sinclair
-* Michael Granger
-* Michael Neumann
-* Florian Frank
-* Mohammad Khan
-* Derek Lewis
-* Thomas-Ivo Heinen
-* Jan Molic
-
-This package is a collection of work by many persons. 
-The actual code on is licensed according to the original authors
-desires, being one of the following: Ruby, GPL, LGPL, MIT, or Artistic.
-Copies of these licenses should accompany this document. Any piece of code
-not specifically laballed shall fall under the Ruby License.
-   
-[Please Note: I am working to make sure everything is labeled appropriately.
-Please forgive me if I have not done so in a particular place --just let 
-me know and I will fix.]
-
-Also, I would like to ask all those authors, whose code is collected here,
-to consider allowing me to move to the Ruby license, so one license can serve
-for all.
+* George Moschovitis
+* Peter Vanbroekhoven
+* Florian Gross
+
+See the AUTHORS file for a list of all other contributing Rubyists.
+
+If anyone is missing from the list, please let me know and 
+I will correct right away. Thanks.
 
 
 == License
 
-The collection per collection is licensed as follows:
+In so far as it matters, the collection PER COLLECTION is licensed 
+as follows:
 
-  Ruby Facets, the Fantastic Atomic Core Extensions
+  Ruby Facets
   Copyright (c) 2004,2005 Thomas Sawyer
   Ruby License
 
 The Ruby license is a dual license that also provides for use of the GPL.
-A copy of both licenses should accompany this document.
-
+A copy of both licenses accompany this document (see COPYING).
 
-== Mascot
+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.)
 
-Does evey good project need a mascot? Well then, Facets
-has the Raspberry. Why the Raspberry? Because it is 
-Red and Faceted, of course. :)
+Any code file not specifically labelled shall fall under the Ruby License.
 
 
 == Pitch
@@ -178,3 +206,18 @@ Red and Faceted, of course. :)
   ALL YOUR BASE ARE BELONG TO RUBY
 
 
+----
+
+[1] A lot of mental anguish went into finding a good title 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?
+
+