facets 1.4.0 → 1.4.1

data/note/history/INTRO

@@ -0,0 +1,172 @@
+
+= Ruby Calibre, Common Applications Library Suite
+
+  "ALL BASE COMMON"
+
+== Introduction
+
+Welcome to the Ruby Calibre Project[1].
+
+Calibre is an open API repository project for the Ruby programming language.
+The intent of the project is to provide extensive general purposed library
+collections to supplement the core and standard libraries already
+included with Ruby. Specifically, it is an free and open repository of
+useful and well tested classes, modules, mixins and methods.
+
+Calibre has a simple slogan, "ALL BASE COMMON". The notion is that small 
+commonly used tools are better served whole. There are a number of 
+advantages in bundling these into a single suite.
+
+  * Better code reuse
+  * Collabretive improvements
+  * Name consistency
+  * One-stop shop and installation
+
+The name Calibre is derived from the term used in gemstones:
+  
+  "Calibre-cut stones are small stones that are cut into special shapes
+   that are meant for use in commonly-used designs."
+
+So you see, the gemstone analogy is perfect. :)
+
+The project is presently divided into two parts.
+
+The first and most fundemental of these is Ruby Facets, the Fantasic Atomic
+Core Extensions. The uniquness of this library collection lies in the
+atomicity of its extensions layout (hence the name) --nearly every core
+extension method is in it's own file, so it can be required independently.
+
+The second is Cuts&Carats, a Collection of API Useful Tools. This is a higher-level
+general purpose library which includes classes, modules, mixins, and other
+assorted general purposed additions.
+
+All Calibre libraries include expiremental development repositories where
+new potential additions are kept for research and testing. Please,
+feel free to explore these repositories and help contribute to those
+works-in-progess. If you have something you'd like to add, please
+submit and it will be placed into the appropriate development area,
+where it will reside until deemed fit for inclusion in the main.
+
+  Note: Calibre is still a young project so a number of libs
+  still need improvements despite their inclusion in the main.
+
+
+== Installation
+
+presently only a manual install is avaliable but it is simple enough
+in that it uses setup.rb. Simply uncompress the package and run
+setup.rb. For example:
+  
+  > tar -xvzf trix-x.y.z.tar.gz
+  > cd trix-x.y.z
+  > sudo ruby setup.rb
+
+
+== Usage
+
+Umm... that might require a book. You should look at the API RDocs.
+To date, not everything in documented. But it's getting there.
+You are welcome to help out. The basic requires are:
+  
+  require 'calib/<file>'
+  
+  require 'calib/cut/<file>'
+  require 'calib/carat/<file>'
+
+  require 'facet/<file>'
+  require 'facet/<class>/<file>'
+
+For instance:
+  
+  require 'facet/nil/empty?'
+
+The #empty? method will be the only new method added to NilClass. 
+In the Facet's lib almost every file is named for the method in 
+contains. The only exceptions are for methods that are tightly 
+related. In these few cases either the file will be named after
+the "core" method, or named as a conjunction, like +true&false?.rb+.
+
+
+== Mascots
+
+Doesn't every good project need a mascot? Well, ours is the Raspberry,
+becasue it's red and faceted. But we also like Carrots, Baseball Diamonds
+and Swirling Atoms. :)
+
+==== Why Raspberry?
+
+Becasue it adds color (namely red) and a nice flavor to the whole affair.
+
+
+== Authorship
+
+This collection was put together by, and much of it written by Thomas Sawyer
+(aka T. Onoma). He can be reached via email at transami at runbox.com.
+
+This package is a collection of work by many persons. 
+If it matters, the collection(s) per collection(s) is licensed:
+
+  Calibre, Common Application Libraries
+  Copyright (c) 2004 Thomas Sawyer
+  Ruby License
+
+  Carats, the Ruby Toolchest
+  Copyright (c) 2004 Thomas Sawyer
+  Ruby License
+  
+  Cuts, Common Useful Tools
+  Copyright (c) 2004 Thomas Sawyer
+  Ruby License
+  
+But the individual pieces of code are licensed according to the original authors
+desires, thus far 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 moving to a common license, assumedly the Ruby license,
+  so one license can serve for all.
+
+=== Contributing Authors
+
+This follwoing is a list code contributors.
+(Please notify me, if anyone is missing.)
+
+* Thomas Sawyer      <transami#runbox.com>
+* Paul Brannan       <paul#atdesk.com>
+* Renald Buter       <buter#cwts.nl>
+* Daniel J. Berger
+* Hal Fulton         <hal9000#hypermetrics.com>
+* Gavin Sinclair     <gavin#>
+* Michael Granger    <ged#FaerieMUD.org>
+* Michael Neumann    <mneumann#ntecs.de>
+* Florian Frank
+* Mohammad Khan      <mkhan#lextranet.com> 
+* Derek Lewis        <lewisd#f00f.net>
+* Thomas-Ivo Heinen
+* Jan Molic
+* Shashank Date
+* Austin Ziegler     <halostatue#gmail.com>
+
+
+== Pitch
+
+  ALL YOUR BASE ARE BELONG TO RUBY
+
+
+----
+
+
+[1] A lot of mental anguish went into finding good titles. Of course in the end,
+    only one theme could take the honor. Other good names that were considered were
+    Ruby Warchest w/ Atomix, Ruby Downs & Ace, Ruby Pillbox & Pills (a _why suggestion),
+    and one that almost won out, Trix & Atomx. Of course, let us not forget even older
+    "working" names that were used along the way: Tomslib, Succ, ABC and finally Raspberry.
+
+
+# Copyright (c)2004 Thomas Sawyer 
+# --.com : The web page without a name.

data/note/history/README

@@ -0,0 +1,223 @@
+
+= Ruby Facets
+
+  "ALL BASE COMMON"
+
+
+== Introduction
+
+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 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.
+
+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.
+
+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
+
+
+== Status
+
+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, 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
+
+For detailed usage of any given method or module please refer to the
+API RDocs. Most are well documented.
+
+Although not at all neccessary it is recommended that before requiring
+any other facet you first require the main facility.
+
+  require 'facets'
+
+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:
+
+  require 'facet/time/stamp'  # TOO BE DEPRECATED !!!
+
+You should begin transitioning to:
+
+  Time.use Facets, :stamp
+
+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.
+
+  Array.use Facets, :each_permutation
+
+Even though #each_permutation is a method of Enumerable this will still work
+because Enumerable is a superclass of Array.
+
+Also it allows for the use operators without special recourse.
+For instance, the Proc compostion operator can be require simply.
+
+  Proc.use Facets, :*
+
+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.
+
+Some extension methodsets are also available. These are loaded in traditional
+manner. 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!
+
+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:
+
+  require 'facet/units'
+
+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]
+
+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 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, 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
+* 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
+
+In so far as it matters, the collection PER COLLECTION is licensed 
+as follows:
+
+  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 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.)
+
+Any code file not specifically labelled shall fall under the Ruby License.
+
+
+== Pitch
+
+  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?
+
+

data/note/history/README-OLD

@@ -0,0 +1,180 @@
+
+= Ruby Facets
+
+== What is this?
+
+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
+
+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.
+
+=== The Classes, Modules and Mixins
+
+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.]
+
+In short, through a single package, the Ruby programmer is treated to a
+plethora of programming tools.
+
+
+== Calibre
+
+Ruby Facets is part of the Calibre project. You can learn more at:
+
+  http://calibre.rubyforge.com
+
+
+== 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
+  > 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.
+
+The general require statement for an atomic facet is as follows: 
+
+  require 'facet/<class|module>/<method-name>'
+
+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'
+
+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. 
+
+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}/'.
+
+The two most notable shortcuts are 'base' and 'common'.
+If you wish to include all the methods considered basic:
+
+  require 'facet/base'
+
+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":
+
+  require 'facet/common'
+
+This is a large selection of methods that are considered the most 
+often useful.
+
+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.
+
+On top of all this there are the non-atomic additions. These never
+fall into a subdirectory, and can always be require accordingly:
+
+  require 'facet/{file-name}'
+
+As for actual examples, well that might require a book.
+But again, refer to the API docs.
+
+
+== Contribute
+
+The project thrives on contribution. Please feel free to offer any
+extension you wish. The criteria for inclusion is fairly light:
+
+* Is it generally useful and/or highly interesting? 
+* Does it pass a basic testcase?
+
+If it meets these requirements then it will in all likelihood 
+be accepted into the main facets lib. 
+
+
+== 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.
+
+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.
+
+* 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.
+
+
+== License
+
+The collection per collection is licensed as follows:
+
+  Ruby Facets, the Fantastic Atomic Core Extensions
+  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.
+
+
+== Mascot
+
+Does evey good project need a mascot? Well then, Facets
+has the Raspberry. Why the Raspberry? Because it is 
+Red and Faceted, of course. :)
+
+
+== Pitch
+
+  ALL YOUR BASE ARE BELONG TO RUBY
+
+