= Ruby Facets

"ALL YOUR BASE ARE BELONG TO RUBY"


== Introduction

Ruby Facets is the premiere collection of general purpose method
extensions and standard additions for the Ruby programming language.

Facets houses the largest single collection of methods available for
extending 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 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.

In addition Facets provides a collection of extensions to Ruby standard library
plus a small collection of add-on classes and modules. Together these
libraries constitute an ever improving source of reusable components, suitable
to a wide variety of usecases.


== Resources

* Homepage: http://rubyworks.github.com/facets
* Report Bugs: http://github.com/rubyworks/facets/issues
* Mailing List: http://groups.google.com/group/facets-universal/topics
* Wiki Pages: http://wiki.github.com/rubyworks/facets
* Source Code: http://github.com/rubyworks/facets


== 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 better organized online documentation 
is available at http://rubyworks.github.com/facets/learn.html.

* Core API: http://rubyworks.github.com/facets/doc/api/core/index.html
* More API: http://rubyworks.github.com/facets/doc/api/more/index.html
* Tour API: http://rubyworks.github.com/facets/doc/api/tour/index.html


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

Facets 2.8+ requires Ruby 1.8.7 or higher.


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

=== CORE Library

At the heart of Ruby Facets is the CORE extensions library. CORE provides
a sizable collection of generally useful methods, along with a few supporting
classes, that extend the functionality of Ruby's core classes and modules.

With the exception of a few *uncommon* extensions, CORE contains anything that
will load automatically when issuing:

  require 'facets'

This loads all the CORE functionality at once. If you plan to use more then a
handful of Facets core methods it is recommended that you require the library in
this way.

Of course you can use the CORE library piecemeal if you prefer. And for uncommon
extension this must be done. The general require statement for a core extensions
library is:

  require 'facets/<class|module>/<method-lib>'

For example:

  require 'facets/time/stamp'

Most "atoms" contain only one method, but a few exceptions occur when methods
are closely tied together.

You can load per-class or per-module groups of core methods by requiring the
class or module by name. For example"

  require 'facets/time'

Will require all the core Time method extensions.

Note that some methods that were part of CORE in 1.8 and earlier are now part
of MORE libraries. A good example is 'random.rb'. There were separated because
they had more specialized use cases, where as CORE extensions are intended as
general purpose.

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}'

==== Method File Names

Operator method redirect files are stored using English names. For instance for
Proc#* is 'proc/op_mul'.

For reference, here is the chart.

     +@   => op_plus
     -@   => op_minus
     +    => op_add
     -    => op_sub
     **   => op_pow
     *    => op_mul
     /    => op_div
     %    => op_mod
     ~    => op_tilde
     <=>  => op_cmp
     <<   => op_lshift
     >>   => op_rshift
     <    => op_lt
     >    => op_gt
     ===  => op_case
     ==   => op_equal
     =~   => op_apply
     <=   => op_lt_eq
     >=   => op_gt_eq
     |    => op_or
     &    => op_and
     ^    => op_xor
     []=  => op_store
     []   => op_fetch

Facets simply takes the '*' and translates it into a string acceptable to all
file systems. Also, if a method ends in '=', '?' or '!' it is simply removed.


=== MORE Library

On top of the extensive CORE library, Facets provides extensions for Ruby's
standard library, as well as very small collection of additional modules and
classes to supplement it.

Use the More library like you would any other 3rd party library.
The only difference between Facets More library and other libraries
is the lack of any enclosing @Facets::@ namespace. This is becuase
the libraries provided by Facets are considerd fairly low-level.

When using Facets' extended versions of Ruby's standard libraries,
the More libraries have to loaded manually, of course. However you
do not need to load Ruby's library first, as the Facets' library
will do that automatically.

For example, normally one load Ruby's OpenStruct class via:

  require 'ostruct'

To load 'ostruct.rb' plus Facets extensions for it simply use:

  require 'facets/ostruct'

instead.

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,2010 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.


"ALL YOUR BASE ARE BELONG TO RUBY!"

Ruby Facets, Copyright (c)2005,2006,2007,2008,2009,2010 Thomas Sawyer

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