Ruby Facets

  "ALL BASE COMMON"

Introduction

Ruby Facets

Facets is set of two libraries Facets/CORE and Facets/MORE.

Facets/CORE is a vast collection of methods which extend the core capabilities of Ruby’s built-in classes and modules. This 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.

Facets/MORE is a collection of additioanl classes, modules and microframeworks. The class, module and microframework additions consitute an ever growing and improving source of reusable components. Some very nice additions are available, 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.

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 everyone. 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 some parts are still considered beta, everything is relatively usable.

Installation

The easiest way to install is via RubyGems. On the command line enter:

  > gem install facets

To manually install, unpack the .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 single CORE facet you simply require the method by name, for example:

  require 'facet/time/stamp'

Techinally this requires a redirection file to the core method itself. Redirection can be bypassed. Eg.

  require 'facets/core/time/stamp'

But this usage is discouraged and should only be used if it is for some reason neccessary or you are developing a library for Facets itself.

If you are using more then a few facets it is recommended that before requiring any of them you first require the main facility.

  require 'facets'

This loads a set of facets considered "base" —currently a couple dozen very basic methods, and adds the facets library directories to the end of Ruby’s load path. This allows you to require facets without even using the ‘facet/…’ prefix. Eg.

  require 'string/blank'

A handful of extension sets are also available. For example,

  require 'facet/string_as_array'

adds some methods to Array that allow a String to behave more like an array of characters. Other 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.

It also should be pointed out that class methods are stored under the ‘self’ directory of a class. For example, to load the File::read_list method.

  require 'facet/file/self/read_list'

Using a Facets/MORE library of modules, classes or microframeworks is essentially the same. You can use the redirection path. Eg.

  require 'facet/basicobject'

Or do so directly.

  require 'facets/more/basicobject'

Again, if you load the main facility, you can eliminate the need for the ‘facet/’ prefix.

  require 'facets'
  require 'basicobject'

Understand that on the off chance that another library has the same name as one of Facets’ everything will still work fine. You will just not be able to use the prefixless shorcut to require it.

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

Notes

Directories

There are two subdirectories in Facets library, ‘core’, which stores the method extensions and ‘more’ which store the modules, classes and micorframeworks.

The layout of Facets’ core method files is straightfoward and well organized. All individual methods are stored in subdirectories under their effected downcased class’ or module’s name.

  '<class|module>/<method-name>'

Class method are stored in the same manner but under a ‘self’ subdirectory.

  'core/<class|module>/self/<method-name>'

Method File Names

Operators are stored in the file system using english names. For instance for Proc#* is ‘proc/op_mul’.

For reference, here is the chart.

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

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.

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-2006 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).

Credit and Copyrights for particular borrowed code segments 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 lincense.</p>

Pitch

  ALL YOUR BASE ARE BELONG TO RUBY