= Ruby Facets

  http://facets.rubyforge.com

  "ALL YOUR BASE ARE BELONG TO RUBY"


== Introduction

Ruby Facets is the single largest collection of general purpose method
extensions and system additions for the Ruby programming language.

The CORE extensions is a large collection of methods which extend the
core capabilities of Ruby's built-in classes and modules. This collection
of extension methods are unique by virtue of their atomicity. The methods
are generally stored in individual files so that each can be required
independently. This gives developers the potential for much finer control
over which extra methods to bring into their code.

The MORE additions are a collection of classes, modules and lightweight systems
which constitute an ever improving source of reusable components. This set of
libraries is kept light and focused on useful to a wide variety of usecases.


== Release Notes

Please see Facets Blog (http://facets.rubyforge.org).


== Documentation

Facets has special documentation needs due to it's extensive bredth.
The RDocs generated when installing via RubyGems, are unweildly because it
combines all of Facets in one set of docs. Hopefully we can remedy this in
the future. In the mean time the gem package includes better documentation
--divided into two sections in the doc/rdoc directory.

Online documentaiton is available at http://facets.rubyforge.org/learn.html.
There is a "Quick Doc" feature that can be a bit more convenient then the usual
RDocs. Prior to 2.3.1 off-line docs had to be downloaded via a separate package,
but this is no longer the case. I've seen past the stigma of not including
documentation along with the package itself (the extra 500K isn't even a floppy
disk folks!), so you will find them in the doc/ directory of whatever package
you have choosen to install. In fact, a good package installer should give you
the option to install those in the appropriate place in your system anyway
(eg. in /usr/share/doc/facets/).


== Installation

The easiest way to install is via RubyGems.

  $ gem install facets

To install manually, your will need Ruby Setup (http::/setup.rubyforge.org).
Then download and unpack the .tar.gz package and run:

  $ tar -xvzf facets-2.x.x.tar.gz
  $ cd facets-2.x.x
  $ sudo setup.rb


== Compatibility with 1.x series.

Prior to 2.0, Facets was divided between CORE and MORE --standalone extensions 
vs. classes and modules, respectively. With 2.0, the notion of "CORE" has taken
on a slightly different meaning. Instead CORE now consists of the libraries that
are thought "essential" and as such are loaded automatically when using 
++require "facets"++. While still primarily made up of extension methods, some 
modules and classes may now belong to core as well.


== Mission

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 the community. There are a number of advantages here:

    * Better Code-reuse
    * Collaborative Improvements
    * Greater Name Consistency
    * One-stop Shop and Installation


== Usage

For information in usage, please see the special README for the specific
set of libraries:

  README.core     Core Extensions
  README.more     Standard Extensions & Additions

General usage of the CORE library is provided via:

  require 'facets'

This is the recommended usage. However, you can also "cherry pick" core
methods. While there are exceptions the rule of thumb for loading a core
method is:

  require 'facets/{class|module}/{method}'

See README.core for more information.

Using the Facets/MORE library of modules, classes or microframeworks is
essentially the same. For example:

  require 'facets/basicobject'

Again, for details pertaining to the functionality of each feature, please see
the API Docs.


== Contribute

This project thrives on contribution.

If you have any extension methods, classes, modules or small frameworks that
you think have general applicability and would like to see them included in
this project, don't hesitiate to submit. Also, if you have better versions
of any thing already included or simply have a patch, they are more than
welcome. We want Ruby Facets to be of the highest quality.


== Authors

This collection was put together by, and largely written by Thomas Sawyer
(aka Trans). 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 exceptions I have included the copyright notice with the
source code.

Any code file not specifically labeled 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 acknowledgments embedded in the
source code. You can see them in "CREDIT:" lines or as file-base "Author(s)"
sections given in the RDocs. 

Also see the AUTHORS file for a list of all 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:

  Ruby Facets
  Copyright (c) 2004-2006 Thomas Sawyer

  Distributed under the terms of the Ruby license.

The Ruby license is a dual license that also provides for use of the GPL.
Complete texts of both licenses accompany this document (see LICENSE).

Acknowledgments and Copyrights for particular snippets of borrowed code
are given in their respective source. All licenses are either compatible
with the Ruby license (namely the GPL) or the original author has given
permission for inclusion of their code under such license.


Ruby Facets, Copyright (c)2005,2006,2007,2008 Thomas Sawyer / Tiger Ops

ALL YOUR BASE ARE BELONG TO RUBY!

Do you Ruby? (http://ruby-lang.org)

