ANN: Facets 2.0

Facets 2.0 is out!

http://facets.rubyforge.org

Facets 2.0.0 represent the project’s initial push into official
“production
ready” status --a departure from the 1.x series which was
focused on acquiring functionality. For more information about this
release see the README below.

As with any zero-point release, I expect some minor releases to
follow. Please, let me know if you encounter any problems so I
can get them fixed right away.

Special thanks to everyone that helped me get this major release
together!

gem install facets

T.

= Ruby F.s

http://facets.rubyforge.com

“ALL YOUR BASE ARE BELONG TO RUBY”

== Introduction

Ruby F.s 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 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.

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.

== Installation

The easiest way to install is via RubyGems.

$ gem install facets

To install manually, download and unpack the .tar.gz package and use
the included
task/install script. Eg.

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

On Window the last step will be:

C:> ruby task/setup

IMPORTANT! Note that setup.rb is no longer used b/c of Facets’ new
layout.

== 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 only a slightly differnt 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.

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. It makes it possible to load Facets libraries on a per method
basis, just as before, via require redirection. For example:

require ‘facets/string/underscore’

Will redirect according to the content of the underscore.rb file which
is:

require ‘facets/string/stylize’

So the underscore method will be loaded just as before. But a few
other stylization methods will also be loaded. This actually proves
a more useful approach because quite often a related method is needed
as well.

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 (http://
blow.rubyforge.org), inflection libraries are in English (http://
english.rubyforge.org), units.rb along with constants.rb are in Stick
(http://stick.rubyforge.org), and the persistance system in Opod
(http://opod.rubyforge.org).

== 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 of Facets is very good. While some libs could still
use some “finishing” work, all are highly API stable and functional.

== Usage

For detailed usage of any given method or module please refer to the
API RDocs.

http://facets.rubyforge.org/learn.html

Most of Facets if fairly well documented. Assistance in improving
documentation though is always appreciated.

If you plan to use more then a few of Facets core method it is
recommended that you require require the main facility.

require ‘facets’

This loads all the CORE functionality at once.

Of course you can use the CORE library piecemeal if you prefer. The
general require statement for a core extensions library is:

require ‘facets/<class|module>/’

For example:

require ‘facets/time/stamp’

Most “atoms” contain only a few methods, sometimes only one, but a few
exceptions provide quite a few method, such as ++string/indexable.rb+
+.

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 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 b/c they had more specialized usecases, where as CORE
extensions are intended as general purpose.

Using a 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.

== 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_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 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 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 F.s 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, and an unobtrusive “Author(s)” section is
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 F.s
Copyright (c) 2004-2006 Thomas S.

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 doc/
COPYING).

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of
the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the
Free Software Foundation, Inc.
59 Temple Place, Suite 330
Boston, MA 02111-1307 USA

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.

What does ruby facets do?

Trans [email protected] wrote: Facets 2.0 is out!

http://facets.rubyforge.org

Facets 2.0.0 represent the project’s initial push into official
“production
ready” status --a departure from the 1.x series which was
focused on acquiring functionality. For more information about this
release see the README below.

As with any zero-point release, I expect some minor releases to
follow. Please, let me know if you encounter any problems so I
can get them fixed right away.

Special thanks to everyone that helped me get this major release
together!

gem install facets

T.

= Ruby F.s

http://facets.rubyforge.com

“ALL YOUR BASE ARE BELONG TO RUBY”

== Introduction

Ruby F.s 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 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.

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.

== Installation

The easiest way to install is via RubyGems.

$ gem install facets

To install manually, download and unpack the .tar.gz package and use
the included
task/install script. Eg.

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

On Window the last step will be:

C:> ruby task/setup

IMPORTANT! Note that setup.rb is no longer used b/c of Facets’ new
layout.

== 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 only a slightly differnt 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.

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. It makes it possible to load Facets libraries on a per method
basis, just as before, via require redirection. For example:

require ‘facets/string/underscore’

Will redirect according to the content of the underscore.rb file which
is:

require ‘facets/string/stylize’

So the underscore method will be loaded just as before. But a few
other stylization methods will also be loaded. This actually proves
a more useful approach because quite often a related method is needed
as well.

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 (http://
blow.rubyforge.org), inflection libraries are in English (http://
english.rubyforge.org), units.rb along with constants.rb are in Stick
(http://stick.rubyforge.org), and the persistance system in Opod
(http://opod.rubyforge.org).

== 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 of Facets is very good. While some libs could still
use some “finishing” work, all are highly API stable and functional.

== Usage

For detailed usage of any given method or module please refer to the
API RDocs.

http://facets.rubyforge.org/learn.html

Most of Facets if fairly well documented. Assistance in improving
documentation though is always appreciated.

If you plan to use more then a few of Facets core method it is
recommended that you require require the main facility.

require ‘facets’

This loads all the CORE functionality at once.

Of course you can use the CORE library piecemeal if you prefer. The
general require statement for a core extensions library is:

require ‘facets//’

For example:

require ‘facets/time/stamp’

Most “atoms” contain only a few methods, sometimes only one, but a few
exceptions provide quite a few method, such as ++string/indexable.rb+
+.

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 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 b/c they had more specialized usecases, where as CORE
extensions are intended as general purpose.

Using a 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.

== 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_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 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 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 F.s 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, and an unobtrusive “Author(s)” section is
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 F.s
Copyright (c) 2004-2006 Thomas S.

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 doc/
COPYING).

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of
the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the
Free Software Foundation, Inc.
59 Temple Place, Suite 330
Boston, MA 02111-1307 USA

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.

On Oct 4, 11:28 am, Wendell H. [email protected] wrote:

What does ruby facets do?

Ruby F.s is a large collection of general purpose method
extensions and class/module additions for Ruby.

This page will probably give you the best “quick start” idea of what
it can do:

http://facets.rubyforge.org/learn.html

T.

On Oct 5, 2:17 am, “Chauk-Mean P.” [email protected] wrote:

I just noticed that the gem installation doesn’t install the
documentation even if I explicitly request it.

Yes. That’s because the standard rdoc generation makes a mess of
things --there’s too much in Facets to be rdoc’d as a single library.
There is a specialized task in the package, called ‘task/rdoc’, that
generates decent rdocs, however it requires my ratch build tool which
I haven’t released quite yet. I still have some work to do on the
documentation front (including a documentation wiki I have planed).
But it’s going to take me a little while to get it all squeaky.
Documentation is the main focus of the next “2.1” release actually.

In the mean time, I did make this which is pretty convenient:

http://facets.rubyforge.org/quick.html

I added it to my browser toolbar and set it to open as a sidebar. It
works really well that way.

HTH (Hope That Holds-you-over :wink:
T.

Trans wrote:

In the mean time, I did make this which is pretty convenient:

http://facets.rubyforge.org/quick.html

It helps but I don’t have direct access to the Internet. It would be
great if you can make a downloadable archive of this documentation.

Cheers.

CM

Trans wrote:

Facets 2.0 is out!

== Installation

The easiest way to install is via RubyGems.

$ gem install facets

Great news !
I just noticed that the gem installation doesn’t install the
documentation even if I explicitly request it.

Chauk-Mean.

Trans wrote:

On Oct 5, 5:37 am, “Chauk-Mean P.” [email protected] wrote:

Trans wrote:

In the mean time, I did make this which is pretty convenient:

http://facets.rubyforge.org/quick.html

It helps but I don’t have direct access to the Internet. It would be
great if you can make a downloadable archive of this documentation.

I see. Hmm… Are you using Linux/MacOs or Windows?

I’m running Windows.

CM.

On Oct 5, 5:37 am, “Chauk-Mean P.” [email protected] wrote:

Trans wrote:

In the mean time, I did make this which is pretty convenient:

http://facets.rubyforge.org/quick.html

It helps but I don’t have direct access to the Internet. It would be
great if you can make a downloadable archive of this documentation.

I see. Hmm… Are you using Linux/MacOs or Windows?

T.

On 10/4/07, Trans [email protected] wrote:

Facets 2.0 is out!

Trans, thanks! I haven’t used this library directly yet, but after
perusing it, I’ll definitely be using it a lot. Keep up the good
work!

Todd

On Oct 5, 6:20 am, “Chauk-Mean P.” [email protected] wrote:

I see. Hmm… Are you using Linux/MacOs or Windows?

I’m running Windows.

Okay. At first I was going to suggest a quick hack of using wget to
pull the whole website to your local disk, but instead I went ahead
and put together a little docs package you can use off line. Look at
the bottom of the page at:

http://rubyforge.org/frs/?group_id=804

You’ll see a facets-doc-2.0.0 package. That has has the rdocs and the
quick api. Note that, when you unpack it, it will create a directory
called ‘quick/’. Let me know if you have any trouble with it.

Thanks for the idea by the way. I kind of like this. If it proves
itself, I will continue to support the docs package and improve upon
it with ri docs and a snapshot of the current docs wiki (once that’s
up).

Thanks,
T.

Odd, I’m getting “404 not found” for both of the doc files.

Just noticed that the Installation section of the README I attached
had a misprint. In the example ‘task/setup’ should be ‘task/install’.
I reprinted the corrected section below.

T.

== Installation

The easiest way to install is via RubyGems.

$ gem install facets

To install manually, download and unpack the .tar.gz package and use
the included task/install script. Eg.

$ tar -xvzf facets-2.x.x.tar.gz
$ cd facets-2.x.x
$ sudo task/install

On Windows the last step will be:

C:> ruby task/install

Note that setup.rb is no longer used b/c of Facets’ new specialized
layout.

On Oct 5, 6:26 am, “Todd B.” [email protected] wrote:

On 10/4/07, Trans [email protected] wrote:

Facets 2.0 is out!

Trans, thanks! I haven’t used this library directly yet, but after
perusing it, I’ll definitely be using it a lot. Keep up the good
work!

Hey, thanks for the recognition. It’s nice to be useful! :slight_smile:

T.

Trans wrote:

On Oct 5, 6:20 am, “Chauk-Mean P.” [email protected] wrote:

I see. Hmm… Are you using Linux/MacOs or Windows?

I’m running Windows.

Okay. At first I was going to suggest a quick hack of using wget to
pull the whole website to your local disk, but instead I went ahead
and put together a little docs package you can use off line. Look at
the bottom of the page at:

http://rubyforge.org/frs/?group_id=804

You’ll see a facets-doc-2.0.0 package. That has has the rdocs and the
quick api. Note that, when you unpack it, it will create a directory
called ‘quick/’. Let me know if you have any trouble with it.

I got the zip file and it works perfectly. Thanks.

Cheers.

CM.

On Fri, 05 Oct 2007 22:26:50 +0900, Todd B. wrote:

On 10/4/07, Trans [email protected] wrote:

Facets 2.0 is out!

Trans, thanks! I haven’t used this library directly yet, but after
perusing it, I’ll definitely be using it a lot. Keep up the good
work!

I usually do not use facets directly, but it is my first line of
reference
when I think of a method that I’d like to have in ruby :slight_smile:
Trans, thanks for the release.