Path: | README |
Last Update: | Mon Mar 21 13:40:05 EST 2005 |
Ruby Facets, the Fantastic Atomic Core Extensions, is an growing collection of extension methods for Ruby’s core and standard libs. It is an atomic library in that the methods are, to the greatest degree reaonable, packaged individually so that each can be required independently. Facets is an open library and all are wlecome to contribute to it growth. The package currently contains over 200 methods, spanning 26 classes and modules. Facets also includes a repository for experimental works, called facet-dev. This provideds a public location to develop and try nascent extensions, which may eventually make their way into Facets proper.
Ruby Facets is part of the Calibre project. You can learn more at:
http://calibre.rubyforge.com
To 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
There are quite a few methods spread out over numerous classes and methods. For detailed usage please refer to the API RDocs. Most methods are fairly well documented, but not all. Assistance in improving documentation is much appreciated.
The general require statement is as follows:
require 'facet/<class|module>/<method>'
All lowercase. For example, perhaps a paricular application would be better served if the NilClass responded to the empty? message.
require 'facet/nil/empty?'
And the empty? method will then be only new method added.
Almost every file is named for the method in contains. The only exceptions are for methods that are very tightly related. In these cases the file will be named either for the "core" method, or as a conjunction, like first&last.rb.
There are also shortcuts for including selections in mass. In the future there will be more of these. For now there are only the following two.
If you wish to include all the methods consider fundemental "base" methods:
require 'facet/all-base'
This represents a group of about one to 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/all-base-common'
This is a large selection of methods that are considered the most generally useful.
All methods considered "uncommon" must be require individually. Since it is possible for a few of the uncommon methods to conflict with one another, there is no way to include everything.
The project thrives on contribution. Please feel free to offer any extension you wish. The criteria for inclusion is fairly light:
If it meets these requirements then it will in all likelihood be accepted into the main facets lib. Otherwise it may still find a place in the development library. Feel free to explore this facets-dev repository and, if so inclined, help develop what’s there. If you have an underdeveloped extension that you’d like to see developed, please submit it and it can be placed into dev, where it can reside and worked on by the community at large.
Does evey good project need a mascot? Well then, Facets has the Raspberry. Why the Raspberry? Because it is Red and Faceted, of course. :)
This collection was put together by, and largely written by Thomas Sawyer (aka T. Onoma). He can be reached via email at transami at runbox.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.
The collection as a whole is licensed as follows:
Ruby Facets, the Fantastic Atomic Core Extensions Copyright (c) 2004 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.
ALL YOUR BASE ARE BELONG TO RUBY