Nano Methods

Ruby’s Atomic Library

What is Ruby’s Atomic Library?

Nano Methods is the a vast collection of general purpose core extension methods for the Ruby programming language. It is unique in that it is an atomic library – the methods are stored individually so that each can be required independently. This gives the programmer greater control to include only the extra methods he or she actually needs. The package currently contains over 400 methods spanning 27 classes and modules.

Installation

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

> gem install nano

To manually install, unpack the .tbz (.tar.bz2) package and use the included setup.rb script. For example:

> tar -xvzf nano-x.y.z.tbz
> cd nano--x.y.z
> sudo ruby setup.rb

Usage

The Nano Methods

There are quite a few methods. For detailed usage of any given method please refer to the API RDocs. Most are well documented.

You can start using nano simply by requiring methods. For example:

require 'nano/time/stamp'

This works fine for all cases EXCEPT when there is punctuation used in the method name. Nano has used URI escaped codes in those cases. For example.

require 'nano/nilclass/empty%3F'

But who really want’s to hur their brain so? ;) To remedy, you can first,

require 'nano/kernel/require_nano'

Now you can require nano-methods without difficulty. The above becomes:

require_nano 'nilclass/empty?'

The method #require_nano is actually a wrapper around another method #require_esc, except that it automatically furnishes the ‘nano/’ path. You could have instead used:

require_esc 'nano/nilclass/empty?'

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

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

Convenient “require-”groupings“ are kept under the main path-space ‘nano’. The most important among these gorupings is ‘nano/base’. This loads all the nano methods considered fundamental, ie. the ones so basic that Ruby might have just as well had them built-in –about two dozen methods in all (and include require_nano and require_esc). Nano’s base methods are common enough that a direct shortcut has been provided to them via

require 'nano'

Another grouping of interest is ‘nano/full’. This “require-grouping” requires nearly every nano-method there is. The only methods NOT required are those considered “cautionary” or “unsafe” in the way they effect Ruby b/c they may potentially disrupt pre-existing code. (Such “unsafe” methods are not useless however; one just needs to be well aware of their effects and, hence, must require them specifically.)

There are also a number of other sets for requiring methods in mass. For example to load every nano method related to randomness use:

require 'nano/randomness'

The alternative way to use Nano, is the new advance “auto-escape” require system.

require 'nanosys'

This puts in place an alternate Kernel#require method, insuring that all the methods, will be escaped as needed and loaded correctly. After this you can require any nano-method simply by using the normal #require method –no need for the special methods.

Contribute

The project thrives on contribution. Please feel free to offer any extension you wish. The criteria for inclusion is fairly light:

Is it generally useful and/or highly interesting?
Can it pass a basic testcase?

If it meets these requirements then there’s a fair chance that it will be accepted into Nano-Methods.

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 as this library (Ruby). 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 copyrights, thanks and acknowledgements embedded in the source code, and a simple “Author(s)” section is given in the RDocs.

Authors include:

Thomas Sawyer
George Moschovitis
Florian Gross
Gavin Sinclair
Florian Frank
Hal Fulton
Renald Buter
Paul Brannan
Michael Granger
Michael Neumann
Peter Vanbroekhoven
Derek Lewis
Thomas-Ivo Heinen
Mohammad Khan
Jan Molic

If anyone is missing from the above 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:

The Ruby license is a dual license that also provides for use of the GPL. A copy of both licenses accompany this document.

Pitch

ALL YOUR BASE ARE BELONG TO RUBY