
= 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?


