<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>File: README</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<link rel="stylesheet" href=".././rdoc-style.css" type="text/css" media="screen" />
<script language="JavaScript" type="text/javascript">
// <![CDATA[
function toggleSource( id )
{
var elem
var link
if( document.getElementById )
{
elem = document.getElementById( id )
link = document.getElementById( "l_" + id )
}
else if ( document.all )
{
elem = eval( "document.all." + id )
link = eval( "document.all.l_" + id )
}
else
return false;
if( elem.style.display == "block" )
{
elem.style.display = "none"
link.innerHTML = "show source"
}
else
{
elem.style.display = "block"
link.innerHTML = "hide source"
}
}
function openCode( url )
{
window.open( url, "SOURCE_CODE", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=480,width=750" ).focus();
}
// ]]>
</script>
</head>
<body>
<table border='0' cellpadding='0' cellspacing='0' width="100%" class='banner'>
<tr><td>
<table width="100%" border='0' cellpadding='0' cellspacing='0'><tr>
<td class="file-title" colspan="2"><span class="file-title-prefix">File</span><br />README</td>
<td align="right">
<table border='0' cellspacing="0" cellpadding="2">
<tr>
<td>Path:</td>
<td>README
</td>
</tr>
<tr>
<td>Modified:</td>
<td>Mon Feb 18 19:38:06 -0500 2008</td>
</tr>
</table>
</td></tr>
</table>
</td></tr>
</table><br />
<!-- banner header -->
<div id="bodyContent">
<div id="content">
<div class="description"><h1>Ruby Facets</h1>
<pre>
http://facets.rubyforge.com
"ALL YOUR BASE ARE BELONG TO RUBY"
</pre>
<h2>Introduction</h2>
<p>
Ruby Facets is the single largest collection of general purpose method
extensions and system additions for the Ruby programming language.
</p>
<p>
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 stored in relatively small groups of tightly coupled methods 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.
</p>
<p>
The "more" additions are a collection of classes, modules and
light meta-systems which constitutes an ever improving source of reusable
components. Some very nice additions are provided, from the simple Functor
class to a full-blown annotations system.
</p>
<h2>Documentation</h2>
<p>
Facets has special documentation needs due to it‘s extensive bredth.
For this reason, RDocs are not automatically generated when installing via
RubyGems. Unfortunatgely this also prevents RI docs from being created.
Hopefully we can remedy this in the future. In the mean time you can
manually create them by navigating to the package directory (either the gem
or tgz) and running ‘rdoc —ri-site’ (recommended
destination).
</p>
<p>
Online documentaiton is available at <a
href="http://facets.rubyforge.org/learn.html">facets.rubyforge.org/learn.html</a>.
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 (eg. in
/usr/share/doc/facets/).
</p>
<h2>RELEASE NOTES</h2>
<p>
Please see NOTES file.
</p>
<h2>Changes</h2>
<p>
Please see CHANGES file.
</p>
<h2>Installation</h2>
<p>
The easiest way to install is via RubyGems.
</p>
<pre>
$ gem install facets
</pre>
<p>
To install manually, download and unpack the .tar.gz package and use the
included task/install script. Eg.
</p>
<pre>
$ tar -xvzf facets-2.x.x.tar.gz
$ cd facets-2.x.x
$ sudo task/setup
</pre>
<p>
On Window the last step will be:
</p>
<pre>
C:\> ruby task/setup
</pre>
<p>
IMPORTANT! Note that setup.rb is no longer used b/c of Facets’ new
layout.
</p>
<h2>Compatibility with 1.x series.</h2>
<p>
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 only 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 a few classes now belong to core as
well.
</p>
<p>
Additionally, the extension methods are no longer stored on a per-method
basis. While dividing the extension methods up on a per-method basis had
certain advantages, not the least of which was a simple organization, it
proved too granular —more "subatomic" than
"atomic". With 2.0 we have address this issue. All the extension
methods have now been organized into small tightly related groups. However,
being able to require on the basis of a method is still a useful approach,
so a compatibility layer for the 1.x series has been created. <a
href="../classes/It.html">It</a> makes it possible to load Facets libraries
on a per method basis, just as before, via require redirection. For
example:
</p>
<pre>
require 'facets/string/underscore'
</pre>
<p>
Will redirect according to the content of the underscore.rb file which is:
</p>
<pre>
require 'facets/string/stylize'
</pre>
<p>
So the underscore method will be loaded just as before. But a few other
<b>stylization</b> methods will also be loaded. This actually proves a more
useful approach because quite often a related method is needed as well.
</p>
<p>
The other significant change from 1.x to 2.0 is the removal of some
libraries that were considered too extraneous for a general purpose
library. Most of these were spun-off to their own projects. In particular,
the web-related libs are now part of Blow (<a
href="http://blow.rubyforge.org">blow.rubyforge.org</a>), inflection
libraries are in English (<a
href="http://english.rubyforge.org">english.rubyforge.org</a>), units.rb
along with constants.rb are in Stick (<a
href="http://stick.rubyforge.org">stick.rubyforge.org</a>), and the
persistance system in Opod (<a
href="http://opod.rubyforge.org">opod.rubyforge.org</a>).
</p>
<h2>Mission</h2>
<p>
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 everyone. There are a number of advantages here:
</p>
<pre>
* Better Code-reuse
* Collaborative Improvements
* Greater Name Consistency
* One-stop Shop and Installation
</pre>
<h2>Usage</h2>
<p>
For detailed usage of any given method or module please refer to the API
RDocs.
</p>
<pre>
http://facets.rubyforge.org/learn.html
</pre>
<p>
Most libraries are well documented. Assistance in improving documentation
though is always appreciated.
</p>
<p>
If you plan to use more then a few of Facets core method it is recommended
that you require require the main facility.
</p>
<pre>
require 'facets'
</pre>
<p>
This loads all the CORE functionality at once.
</p>
<p>
Of course you can use the CORE library piecemeal if you prefer. The general
require statement for a core extensions library is:
</p>
<pre>
require 'facets/<class|module>/<method-lib>'
</pre>
<p>
For example:
</p>
<pre>
require 'facets/time/stamp'
</pre>
<p>
Most "atoms" contain only a few methods, sometimes only one, but
a few exceptions provide quite a few methods, such as
++string/indexable.rb++.
</p>
<p>
You can load per-class or per-module groups of core methods by requiring
the class or module by name. For example"
</p>
<pre>
require 'facets/time'
</pre>
<p>
Will require all the Time method extensions.
</p>
<p>
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.
</p>
<p>
Using a Facets/MORE library of modules, classes or microframeworks is
essentially the same. For example:
</p>
<pre>
require 'facets/basicobject'
</pre>
<p>
Again, for details pertaining to the functionality of each feature, please
see the API Docs.
</p>
<h2>Method <a href="../classes/File.html">File</a> Names</h2>
<p>
Operator method redirect files are stored using English names. For instance
for <a href="../classes/Proc.html">Proc</a>#* is ‘proc/op_mul’.
</p>
<p>
For reference, here is the chart.
</p>
<pre>
+@ => op_plus_self
-@ => op_minus_self
+ => op_plus
- => op_minus
** => op_pow
* => op_mul
/ => op_div
% => op_mod
~ => op_tilde
<=> => op_cmp
<< => op_lshift
>> => op_rshift
< => op_lt
> => op_gt
=== => op_case_eq
== => op_equal
=~ => op_apply
<= => op_lt_eq
>= => op_gt_eq
| => op_or
& => op_and
^ => op_xor
[]= => op_store
[] => op_fetch
</pre>
<p>
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.
</p>
<h2>Contribute</h2>
<p>
This project thrives on contribution.
</p>
<p>
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. There‘s a
very good chance they 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.
</p>
<h2>Authors</h2>
<p>
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.
</p>
<p>
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.
</p>
<p>
Any code file not specifically labeled shall fall under the Ruby License.
</p>
<p>
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, and an unobtrusive "Author(s)" section is given in
the RDocs.
</p>
<p>
Also see the AUTHORS file for a list of all contributing Rubyists.
</p>
<p>
If anyone is missing from the list, please let me know and I will correct
right away. Thanks.
</p>
<h2>License</h2>
<p>
The collection PER COLLECTION is licensed as follows:
</p>
<pre>
Ruby Facets
Copyright (c) 2004-2006 Thomas Sawyer
Distributed under the terms of the Ruby license.
</pre>
<p>
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).
</p>
<p>
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.
</p>
<p>
ALL YOUR BASE ARE BELONG TO RUBY!
</p>
<p>
Ruby Facets, Copyright (c)2005,2006,2007,2008 Thomas Sawyer
</p>
<p>
Do you Ruby? (<a href="http://ruby-lang.org">ruby-lang.org</a>)
</p>
</div>
</div>
</div>
</body>
</html>