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

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.

To use a 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.

  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.

Some extension method 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!

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?


