= 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