Programming Ruby 1.9 & 2.0: The Pragmatic Programmers’ Guide (2013)

Part 4. Ruby Crystallized

Chapter 28. Standard Library

The Ruby interpreter comes with a large number of classes, modules, and methods built in—they are available as part of the running program. When you need a facility that isn’t part of the built-in repertoire, you’ll often find it in a library that you can require into your program. Sometimes you’ll need to download one of these libraries (perhaps as a Ruby gem).

However, Ruby also ships as standard with a large number of libraries. Some of these are written in pure Ruby and will be available on all Ruby platforms. Others are Ruby extensions, and some of these will be present only if your system supports the resources that they need. All can be included into your Ruby program using require . And, unlike libraries you may find on the Internet, you can pretty much guarantee that all Ruby users will have these libraries already installed on their machines.

Ruby 1.9 has more than 100 standard libraries included in the distribution. For each of these libraries, this section shows a one- or a two-page summary. For each library, we give some introductory notes and typically an example or two of use. You won’t find detailed method descriptions here; for that, consult the library’s own documentation.

It’s all very well suggesting that you “consult the library’s own documentation,” but where can you find it? The answer is that it depends. Some libraries have already been documented using RDoc (see Chapter 19, Documenting Ruby). That means you can use the ri command to get the documentation.

If there’s no RDoc documentation available, the next place to look is the library. If you have a source distribution of Ruby, these library files are in the ext/ and lib/ subdirectories. If instead you have a binary-only installation, you can still find the source of pure-Ruby library modules (normally in the lib/ruby/1.9/ directory under your Ruby installation). Often, library source directories contain documentation that the author has not yet converted to RDoc format.

If you still can’t find documentation, turn to your search engine of choice. Many of the Ruby standard libraries are also hosted as external projects. The authors develop them stand-alone and then periodically integrate the code into the standard Ruby distribution. For example, if you want detailed information on the API for the YAML library, Try searching for yaml ruby—you’ll probably end up at http://www.yaml.org/YAML_for_ruby.html .

The next port of call is the ruby-talk mailing list. Ask a (polite) question there, and chances are that you’ll get a knowledgeable response within hours. See the tips in Section 28.4, Mailing Lists for pointers on how to subscribe.

And if you still can’t find documentation, you can always follow Obi Wan’s advice and do what we did when documenting Ruby—use the source. You’d be surprised at how easy it is to read the actual source of Ruby libraries and work out the details of usage.

There are some libraries that we don’t document, either because they are pretty low level or because we cover them extensively elsewhere in the book. These libraries include:

• debug—the Ruby debugger, covered in Section 14.1,Ruby Debugger.
• iconv—has been removed from Ruby 2.0. UseString#encode.^«2.0»
• mkmf—covered in the online guide to extending Ruby.
• objspace—extensions to the ObjectSpace class designed to be used by the Ruby core team.
• psych—an interface to libyaml. You’ll probably just use the YAML library.
• racc—this is the runtime used by the Racc parser generator. If you need this library, you’ll also need the external Racc system.
• rake—see Section 15.6,The Rake Build Tool.
• rdoc—see Chapter 19,Documenting Ruby.
• rubygems—covered in Section 15.5,RubyGems Integration and in Using RubyGems.

28.1 Library Changes in Ruby 1.9

These are the library changes in Ruby 1.9:

• Much of the Complex and Rational libraries are now built in to the interpreter. However, requiring the external libraries adds some functionally. In the case of Rational, this functionality is minimal.
• The CMath library has been added.
• The Enumerator library is now built in.
• The Fiber library has been added (it adds coroutine support to fibers).
• The Fiddle library (an interface to libffi, which supports calling functions in shared librries) is documented as a replacement for DL.
• ftools has been removed (and replaced by fileutils).
• The Generator library has been removed (use fibers).
• Notes on using irb from inside applications have been added.
• jcode has been removed in favor of built-in encoding support.
• The json library has been added.
• The matrix library no longer requires that you include mathn.
• The mutex library is now built in.
• parsedate has been removed. The Date class handles most of its functionality.
• readbytes has been removed. Class IO now supports the method directly.
• A description of Ripper has been added.
• A description of SecureRandom has been added.
• The shell library has been omitted, because it seems more like a curiosity than something folks would use (and it’s broken under 1.9).
• The soap library has been removed.
• I’ve omitted the sync library. It is broken under 1.9, and the monitor library seems to be cleaner.
• Win32API is now deprecated in favor of using the DL library.

^Library Abbrev: Generate Sets of Unique Abbreviations

Given a set of strings, calculates the set of unambiguous abbreviations for those strings and returns a hash where the keys are all the possible abbreviations and the values are the full strings. Thus, given input of “car” and “cone,” the keys pointing to “car” would be “ca” and “car,” and those pointing to “cone” would be “co,” “con,” and “cone.”

An optional pattern or a string may be specified—only those input strings matching the pattern, or beginning with the string, are considered for inclusion in the output hash.

Including the Abbrev library also adds an abbrev method to class Array.

• Shows the abbreviation set of some words:

• A trivial command loop using abbreviations:

^Library Base64: Base64 Conversion Functions

Performs encoding and decoding of binary data using a Base64 representation. This allows you to represent any binary data in purely printable characters. The encoding is specified in RFC 2045 and RFC 4648.[125]

• Encodes and decodes strings. Note the newlines inserted into the Base64 string.

• Produces:

• Now uses RFC 4648 variants:

• Produces:

^Library Benchmark: Time Code Execution

Allows code execution to be timed and the results tabulated. The Benchmark module is easier to use if you include it in your top-level environment.

• Profile
• Compares the costs of four kinds of method dispatch:

• Produces:

• Which is better: reading all of a dictionary and splitting it or splitting it line by line? Use bmbm to run a rehearsal before doing the timing:

• Produces:

^Library BigDecimal: Large-Precision Decimal Numbers

Ruby’s standard Bignum class supports integers with large numbers of digits. The BigDecimal class supports decimal numbers with large numbers of decimal places. The standard library supports all the normal arithmetic operations. BigDecimal also comes with some extension libraries.

bigdecimal/ludcmp

Performs an LU decomposition of a matrix.

bigdecimal/math

Provides the transcendental functions sqrt, sin, cos, atan, exp, and log, along with functions for computing PI and E. All functions take an arbitrary precision argument.

bigdecimal/jacobian

Constructs the Jacobian (a matrix enumerating the partial derivatives) of a given function. Not dependent on BigDecimal.

bigdecimal/newton

Solves the roots of nonlinear function using Newton’s method. Not dependent on BigDecimal.

bigdecimal/nlsolve

Wraps the bigdecimal/newton library for equations of big decimals.

You can find English-language documentation in the file ext/bigdecimal/bigdecimal_en.html in the Ruby source distribution.

^Library CGI: CGI Programming Support

The CGI class provides support for programs used as Common Gateway Interface (CGI) scripts in a web server. CGI objects are initialized with data from the environment and from the HTTP request, and they provide convenient accessors to form data and cookies. They can also manage sessions using a variety of storage mechanisms. Class CGI also provides basic facilities for HTML generation and class methods to escape and unescape requests and HTML.

• CGI::Session
• Escapes and unescapes special characters in URLs and HTML. Numeric entities less than 256 will be encoded based on the encoding of the input string.Other numeric entities will be left unchanged.

• Access information from the incoming request:

• Access form fields from an incoming request. Assume that the following script, installed as test.cgi, was linked to using http://mydomain.com/test.cgi?fred=10&barney=cat:

• If a form contains multiple fields with the same name, the corresponding values will be returned to the script as an array. The [] accessor returns just the first of these—index the result of the params method to get them all.

In this example, assume the form has three fields called “name”:

• Sends a response to the browser. (Not many folks use this form of HTML generation–use one of the templating libraries described in Section 20.3,Templating Systems.

• Stores a cookie in the client browser:

• Retrieves a previously stored cookie:

^Library CGI::Session: CGI Sessions

A CGI::Session maintains a persistent state for web users in a CGI environment. Sessions may be memory resident or may be stored on disk. See the discussion in Sessions for details.

• CGI

^Library CMath: Complex Transcendental Functions

As of Ruby 1.9, the Complex class is built in to the interpreter. There is no need to require the complex library to create and manipulate complex numbers. However, if you want the transcendental functions defined by Math to work with complex numbers, you must also require the cmath library. The functions affected are as follows: acosh , acos , asinh , asin , atan2 , atanh , atan , cosh , cos , exp , log10 , log , sinh , sin , sqrt , tanh , and tan .

The complex library makes these complex functions the default (so, if you require ’complex’, you can use Math::sin and not CMath::sin).

^Library Complex: Complex Numbers

Loads the cmath library, which defines the transcendental functions for complex numbers. It then arranges things so that these complex-aware functions are the ones invoked when you use Math::. The net effect is that, after requiring complex, you can use functions such as Math::sin on any numeric value, including complex numbers.

• Using transcendental numbers with complex arguments will, by default, cause an error:

• Produces:

• However...

^Library Continuation: Continuations

Continuation objects are generated by the Object#callcc method, which becomes available only when the continuation library is loaded. They hold a return address and execution context, allowing a nonlocal return to the end of the callcc block from anywhere within a program. Continuations are somewhat analogous to a structured version of C’s setjmp/longjmp (although they contain more state, so you may consider them closer to threads). This (somewhat contrived) example allows the inner loop to abandon processing early.

• Does a nonlocal exit when a condition is met:

• Produces:

• The call stack for methods is preserved in continuations:

• Produces:

^Library coverage: Experimental Code Coverage Analysis

The coverage module counts the number of times each line of Ruby code is executed in one or more source files and provides a summary as a hash. The keys of the hash are the names of files that were analyzed, and the values are each an array containing counts (on a per-line basis).

Here’s a simple implementation of the Fizz Buzz program:

And here’s a program that loads and runs that program, using the coverage library to report on execution counts. (Note that it discards the output of the FizzBuzz program, simply to save space on this page.)

Produces:

^Library CSV: Comma-Separated Values

Comma-separated data files are often used to transfer tabular information (and are a lingua franca for importing and exporting spreadsheet and database information). As of Ruby 1.9, the old library has been replaced by James Edward Gray II’s FasterCSV version. It has a few incompatibilities with the original. In particular, CSV.open now works like File.open , not File.foreach , and options are passed as a hash and not positional parameters.

Ruby’s CSV library deals with arrays (corresponding to the rows in the CSV file) and strings (corresponding to the elements in a row). If an element in a row is missing, it will be represented as a nil in Ruby.

The files used in these examples are as follows:

• Reads a file containing CSV data and processes line by line:

• Produces:

• Processes a CSV file that contains a header line. Automatically converts fields that look like numbers.

• Produces:

• Writes CSV data to an existing open stream (STDOUT in this case). Uses | as the column separator.

• Produces:

• Accesses a CSV file as a two-dimensional table:

• Produces:

^Library Curses: CRT Screen Handling

curses or ncurses installed in target environment

The Curses library is a thin wrapper around the C curses or ncurses libraries, giving applications a device-independent way to draw on consoles and other terminal-like devices. As a nod toward object-orientation, curses windows and mouse events are represented as Ruby objects. Otherwise, the standard curses calls and constants are simply defined in the Curses module.

^Library Date/DateTime: Date and Time Manipulation

The date library implements classes Date and DateTime, which provide a comprehensive set of facilities for storing, manipulating, and converting dates with or without time components. The classes can represent and manipulate civil, ordinal, commercial, Julian, and standard dates, starting January 1, 4713 BCE. The DateTime class extends Date with hours, minutes, seconds, and fractional seconds, and it provides some support for time zones. The classes also provide support for parsing and formatting date and datetime strings. The classes have a rich interface—consult the ri documentation for details. The introductory notes in the file lib/date.rb in the Ruby source tree are also well worth reading.

• Experiment with various representations:

• Essential information about Christmas:

• Produces:

^Library DBM: Interface to DBM Databases

a DBM library is installed in target environment

DBM files implement simple, hashlike persistent stores. Many DBM implementations exist: the Ruby library can be configured to use one of the DBM libraries db, dbm (ndbm), gdbm, and qdbm. The interface to DBM files is similar to class Hash, except that DBM keys and values will be strings. This can cause confusion, as the conversion to a string is performed silently when the data is written. The DBM library is a wrapper around the lower-level access method. For true low-level access, see also the GDBM and SDBM libraries.

• gdbm
• sdbm

The following creates a simple DBM file and then reopens it read-only and reads some data. Note the conversion of a date object to its string form.

Produces:

^Library Delegator: Delegate Calls to Other Object

Object delegation is a way of composing objects—extending an object with the capabilities of another—at runtime. The Ruby Delegator class implements a simple but powerful delegation scheme, where requests are automatically forwarded from a master class to delegates or their ancestors and where the delegate can be changed at runtime with a single method call.

• Forwardable
• For simple cases where the class of the delegate is fixed, make the master class a subclass of DelegateClass, passing the name of the class to be delegated as a parameter. In the master class’s initialize method, pass the object to be delegated to the superclass.

• Use SimpleDelegator to delegate to a particular object (which can be changed):

^Library Digest: MD5, RIPEMD-160 SHA1, and SHA2 Digests

The Digest module is the home for a number of classes that implement message digest algorithms: MD5, RIPEMD-160, SHA1, and SHA2 (256, 384, and 512 bit). The interface to all these classes is identical.

• You can create a binary or hex digest for a given string by calling the class method digest or hexdigest .
• You can also create an object (optionally passing in an initial string) and determine the object’s hash by calling the digest or hexdigest instance methods. You can then append to the string using the update method and then recover an updated hash value.
• Calculates some MD5 and SHA1 hashes:

• Produces:

^Library dRuby: Distributed Ruby Objects (drb)

dRuby allows Ruby objects to be distributed across a network connection. Although expressed in terms of clients and servers, once the initial connection is established, the protocol is effectively symmetrical: either side can invoke methods in objects on the other side. Normally, objects passed and returned by remote calls are passed by value; including the DRbUndumped module in an object forces it to be passed by reference (useful when implementing callbacks).

• Rinda
• XMLRPC
• This server program is observable —it notifies all registered listeners of changes to a count value:

• This client program interacts with the server, registering a listener object to receive callbacks before invoking the server’s run method:

^Library English: English Names for Global Symbols

Includes the English library file in a Ruby script, and you can reference the global variables such as $_ using less-cryptic names, listed in the following table. Prior to Ruby 1.9, the name $PROGRAM_NAME was declared using English. It is now predefined in the Ruby interpreter.

The following code shows some regular variable names along with their English counterparts.

Produces:

^Library erb: Lightweight Templating for HTML

ERb is a lightweight templating system, allowing you to intermix Ruby code and plain text. This is sometimes a convenient way to create HTML documents but also is usable in other plain-text situations. See Section 20.3, Templating Systems for other templating solutions.

ERB breaks its input text into chunks of regular text and program fragments. It then builds a Ruby program that, when run, outputs the result text and executes the program fragments. Program fragments are enclosed between <% and %> markers. The exact interpretation of these fragments depends on the character following the opening <%:

Table 26. Directives for ERB

The following code uses <%…%> blocks to execute a Ruby loop, and <%=…%> to substitute a value into the output.

Produces:

An optional second parameter to ERB.new sets the safe level for evaluating expressions. If nil, expressions are evaluated in the current thread; otherwise, a new thread is created, and its $SAFE level is set to the parameter value.

The optional third parameter to ERB.new allows some control of the interpretation of the input and of the way whitespace is added to the output. If the third parameter is a string and that string contains a percent sign, then ERb treats lines starting with a percent sign specially. Lines starting with a single percent sign are treated as if they were enclosed in <%...%>. Lines starting with a double percent sign are copied to the output with a single leading percent sign.

Produces:

If the third parameter contains the string <>, then a newline will not be written if an input line starts with an ERB directive and ends with %>. If the trim parameter contains >>, then a newline will not be written if an input line ends %>.

Produces:

The erb library also defines the helper module ERB::Util that contains two methods: html_escape (aliased as h ) and url_encode (aliased as u ). These are equivalent to the CGI methods escapeHTML and escape , respectively (except escape encodes spaces as plus signs, and url_encode uses %20).

Produces:

You may find the command-line utility erb is supplied with your Ruby distribution. This allows you to run erb substitutions on an input file; see erb --help for details.

^Library Etc: Access User and Group Information in /etc/passwd

Unix or Cygwin

The Etc module provides a number of methods for querying the passwd and group facilities on Unix systems.

• Finds out information about the currently logged-in user:

• Returns the names of users on the system used to create this book:

• Returns the IDs of groups on the system used to create this book:

^Library expect: Expect Method for IO Objects

The expect library adds the method expect to all IO objects. This allows you to write code that waits for a particular string or pattern to be available from the I/O stream. The expect method is particularly useful with pty objects (see the Pty library) and with network connections to remote servers, where it can be used to coordinate the use of external interactive processes.

If the global variable $expect_verbose is true, the expect method writes all characters read from the I/O stream to STDOUT.

• pty
• Connects to the local FTP server, logs in, and prints out the name of the user’s directory. (Note that it would be a lot easier to do this using the net/ftp library.)

• Produces:

^Library Fcntl: Symbolic Names for IO#fcntl Commands

The Fcntl module provides symbolic names for each of the host system’s available fcntl(2) constants (defined in fcntl.h). That is, if the host system has a constant named F_GETLK defined in fcntl.h, then the Fcntl module will have a corresponding constant Fcntl::F_GETLK with the same value as the header file’s #define.

• Different operating system will have different Fcntl constants available. The value associated with a constant of a given name may also differ across platforms. Here are the values on our Mac OS X system:

• Produces:

^Library Fiber: Coroutines Using Fibers

The Fiber class that is built into Ruby provides a generator-like capability—fibers may be created and resumed from some controlling program. If you want to extend the Fiber class to provide full, symmetrical coroutines, you need first to require the fiber library. This adds two instance methods, transfer and alive? , to Fiber objects and adds the singleton method current to the Fiber class.

• It is difficult to come up with a meaningful, concise example of symmetric coroutines that can’t more easily be coded with asymetric (plain old) fibers. So, here’s an artificial example:

• Produces:

^Library Fiddle: Access Dynamically Loaded Libraries (.dll and .so)

The Fiddle module is a wrapper around libffi, a library that provides access to shared libraries. On Windows boxes, it can be used to interface with functions in DLLs. Under Unix it can load shared libraries. Because Ruby does not have typed method parameters or return values, you must define the types expected by the methods you call by specifying their signatures.

• Here’s a trivial C program that we’ll build as a shared library:

• Generates a proxy to access the print_msg method in the shared library. The way this book is built, the shared library is in the same directory as the Ruby code; this directory must be added to the directories searched when looking for dynamic objects. You can do this by setting the DYLD_LIBRARY_PATH environment variable.

• Produces:

^Library FileUtils: File and Directory Manipulation

FileUtils is a collection of methods for manipulating files and directories. Although generally applicable, the model is particularly useful when writing installation scripts and Rake tasks.

Many methods take a src parameter and a dest parameter. If dest is a directory, src may be a single filename or an array of filenames. For example, the following copies the files a, b, and c to /tmp:

Most functions take a set of options. These may be zero or more of the following:

For maximum portability, use forward slashes to separate the directory components of filenames, even on Windows.

FileUtils contains three submodules that duplicate the top-level methods but that have different default options: module FileUtils::Verbose sets the verbose option, module FileUtils::NoWrite sets noop, and FileUtils::DryRun sets verbose and noop.

• un

Produces:

^Library Find: Traverse Directory Trees

The Find module supports the top-down traversal of a set of file paths, given as arguments to the find method. If an argument is a file, its name is passed to the block associated with the call. If it’s a directory, then its name and the name of all its files and subdirectories will be passed in. If no block is associated with the call, an Enumerator is returned.

Within the block, the method prune may be called, which skips the current file or directory, restarting the loop with the next directory. If the current file is a directory, that directory will not be recursively entered. In the following example, we don’t list the contents of the local Subversion cache directories:

Produces:

^Library Forwardable: Object Delegation

Forwardable provides a mechanism to allow classes to delegate named method calls to other objects.

• Delegator
• This simple symbol table uses a hash, exposing a subset of the hash’s methods:

• Forwards can also be defined for individual objects by extending them with the SingleForwardable module. It’s hard to think of a good reason to use this feature, so here’s a silly one:

• Produces:

^Library GDBM: Interface to GDBM Database

gdbm library available

Interfaces to the gdbm database library.[126] Although the DBM library provides generic access to gdbm databases, it doesn’t expose some features of the full gdbm interface, such as the cache size, synchronization mode, reorganization, and locking. Only one process may have a GDBM database open for writing (unless locking is disabled).

• DBM
• SDBM
• Stores some values into a database and then reads them back. The second parameter to the open method specifies the file mode, and the next parameter uses two flags that (1) create the database if it doesn’t exist and (2) force all writes to be synced to disk. Create on open is the default Ruby gdbm behavior.

• Opens a database read-only. The attempt to delete a key would fail.

^Library GetoptLong: Parse Command-Line Options

Class GetoptLong supports GNU-style command-line option parsing. Options may be a minus sign (-) followed by a single character or may be two minus signs (--) followed by a name (a long option). Long options may be abbreviated to their shortest unambiguous lengths.

A single internal option may have multiple external representations. For example, the option to control verbose output could be any of -v, --verbose, or --details. Some options may also take an associated value.

Each internal option is passed to GetoptLong as an array, containing strings representing the option’s external forms and a flag. The flag specifies how GetoptLong is to associate an argument with the option (NO_ARGUMENT, REQUIRED_ARGUMENT, or OPTIONAL_ARGUMENT).

If the environment variable POSIXLY_CORRECT is set, all options must precede nonoptions on the command line. Otherwise, the default behavior of GetoptLong is to reorganize the command line to put the options at the front. This behavior may be changed by setting the attributeGetoptLong#ordering= to one of PERMUTE, REQUIRE_ORDER, or RETURN_IN_ORDER. The environment variable POSIXLY_CORRECT may not be overridden.

• OptionParser

Produces:

^Library GServer: Generic TCP Server

This is a simple framework for writing TCP servers. To use it, subclass the GServer class, set the port (and potentially other parameters) in the constructor, and then implement a serve method to handle incoming requests.

GServer manages a thread pool for incoming connections, so your serve method may be running in multiple threads in parallel.

You can run multiple GServer copies on different ports in the same application.

• When a connection is made on port 2000, responds with the current time as a string. Terminates after handling three requests.

• You can test this server by reading from localhost on port 2000. We use curl to do this—you could also use telnet:

^Library IO/console: Add console support to IO objects

Require io/console, and I/O objects associated with terminals gain the methods IO#raw, IO#raw!, IO#getch, IO#echo=, IO#echo?, IO#noecho, IO#winsize, IO#winsize=, IO#iflush, IO#oflush, and IO#ioflush. The IO class also gains a singleton method, IO.console, which returns an I/O object connected to the controlling terminal of the process.

• Prompt for a password with no echo.

• What’s the size of the controlling terminal?

^Library IO/nonblock: Turn blocking I/O on and off

If a program requires io/nonblock, I/O objects gain the methods IO#nonblock, IO#nonblock?, and IO#nonblock=. The first takes a block, and runs that block with the given file description in nonblocking mode. The second lets you query the blocking status of a file descriptor, and the last lets you turn blocking on and off. You’ll probably want to investigate IO.select, as you’ll need it to tell when the file cn be read or written.

^Library IO/Wait: Check for Pending Data to Be Read

FIONREAD feature in ioctl(2)

Including the library io/wait adds the methods IO#nread, IO#ready?, and IO#wait to the standard IO class. These allow an IO object opened on a stream (not a file) to be queried to see whether data is available to be read without reading it and to wait for a given number of bytes to become available.

• Sets up a pipe between two processes and writes 10 bytes at a time into it. Periodically sees how much data is available.

• Produces:

^Library IPAddr: Represent and Manipulate IP Addresses

Class IPAddr holds and manipulates Internet Protocol (IP) addresses. Each address contains three parts: an address, a mask, and an address family. The family will typically be AF_INET for IPv4 and IPv6 addresses. The class contains methods for extracting parts of an address, checking for IPv4-compatible addresses (and IPv4-mapped IPv6 addresses), testing whether an address falls within a subnet, and performing many other functions. It is also interesting in that it contains as data its own unit tests.

^Library irb: Interactive Ruby

The irb library is most commonly associated with the console command irb. However, you can also start an irb session from within your running application. A common technique is to trap a signal and start irb in the handler.

The following program sets up a signal handler that runs irb when the user hits ^C. The user can change the value of the instance variable @value. When they exit from irb, the original program continues to run with that new value.

Here’s a simple session using it:

^Library json: Generate and Parse JSON Format

JSON is a language-independent data interchange format based on key/value pairs (hashes in Ruby) and sequences of values (arrays in Ruby).[127] JSON is frequently used to exchange data between JavaScript running in browsers and server-based applications. JSON is not a general-purpose object marshaling format. Although you can add to_json methods to your own classes, you will lose interoperability.

• yaml
• Serializes a data structure into a string and writes that to a file:

• Reads the serialized data from the file and reconstitutes it:

• The methods j and jj convert their argument to JSON and write the result to STDOUT (jj prettyprints). This can be useful in irb.

• Produces:

^Library Logger: Application Logging

Writes log messages to a file or stream. Supports automatic time- or size-based rolling of log files. Messages can be assigned severities, and only those messages at or above the logger’s current reporting level will be logged.

• During development, you may want to see all messages:

• Produces:

• In deployment, you can turn off anything below INFO:

• Produces:

• Logs to a file, which is rotated when it gets to about 10KB. Keeps up to five old files.

^Library mathn: Unified Numbers

The mathn library attempts to bring some unity to numbers under Ruby, making classes Bignum, Complex, Fixnum, Integer, and Rational work and play better together. It automatically includes the libraries complex, rational, matrix, and prime.

• Types will tend to convert between themselves in a more natural way (so, for example, Complex::I squared will evaluate to -1, rather than Complex[-1,0]).
• Division will tend to produce more accurate results. The conventional division operator (/) is redefined to use quo , which doesn’t round.
• Related to the previous point, rational numbers will be used in preference to floats when possible. Dividing one by two results in the rational number 1/2, rather than 0.5 (or 0, the result of normal integer division).
• Matrix
• Rational
• Complex
• Prime
• Without mathn:

• With mathn:

^Library Matrix: Matrix and Vector Manipulation

The matrix library defines classes Matrix and Vector, representing rectangular matrices and vectors. As well as the normal arithmetic operations, they provide methods for matrix-specific functions (such as rank, inverse, and determinants) and a number of constructor methods (for creating special-case matrices—zero, identity, diagonal, singular, and vector).

As of Ruby 1.9, matrices use quo internally for division, so rational numbers may be returned as a result of integer division. In prior versions of Ruby, you’d need to include the mathn library to achieve this.

^Library MiniTest: Unit Testing Framework

New in Ruby 1.9, MiniTest is now the standard unit testing framework supplied with Ruby. The minitest library contains classes for unit tests, mock objects, and a (trivial) subset of RSpec-style testing syntax.

The unit testing framework is similar to the original Test::Unit framework. However, if you want functionality that is the same as Test::Unit, use the Test::Unit wrappers for MiniTest—simply require "test/unit" as normal.

Chapter 13, Unit Testing contains a tutorial on unit testing with Ruby.

^Library Monitor: Monitor-Based Synchronization

Monitors are a mutual-exclusion mechanism. They allow separate threads to define shared resources that will be accessed exclusively, and they provide a mechanism for a thread to wait for resources to become available in a controlled way.

The monitor library actually defines three separate ways of using monitors: by subclassing, as a mixin, and as a extension to a particular object. In this section, we show the mixin form of Monitor. The subclassing form is effectively identical. In both it and when including MonitorMixin in an existing class, it is essential to invoke super in the class’s initialize method.

• Thread

Produces:

^Library Mutex_m: Mutex Mix-In

mutex_m is a variant of class Mutex that allows mutex facilities to be mixed into any object.

The Mutex_m module defines methods that correspond to those in Mutex but with the prefix mu_ (so that lock is defined as mu_lock and so on). These are then aliased to the original Mutex names.

• Mutex
• Thread

^Library Net::FTP: FTP Client

The net/ftp library implements a File Transfer Protocol (FTP) client. As well as data transfer commands (getbinaryfile, gettextfile, list, putbinaryfile, and puttextfile), the library supports the full complement of server commands (acct, chdir, delete, mdtm, mkdir, nlst, rename, rmdir, pwd, size, status, and system). Anonymous and password-authenticated sessions are supported. Connections may be active or passive.

• open-uri

produces:

^Library Net::HTTP: HTTP Client

The net/http library provides a simple client to fetch headers and web page contents using the HTTP and HTTPS protocols.

The get post and head methods return a response object, with the content of the response accessible through the response’s body method.

• OpenSSL
• open-uri
• URI
• Opens a connection and fetches a page, displaying the response code and message, header information, and some of the body: