Reading an Entry
Each package (group of modules, packaged for distribution) is summarized in the sections that follow. Each entry has a description of the package as a whole, the version number and date of the version documented, a list of dependencies for use or installation, a synopsis of each module in the package, and an example.
The examples are intended to show a flavor for how the module is used. Most modules have several more examples given in their own documentation.
Version information
The version information given for each module includes both the version number and the date in which the version was uploaded to CPAN. Those modules with low version numbers (less than 1.0) may have major interface changes after this book is published. It is always wise to check the version number of a module against the documentation.
Dependencies
It is assumed by most module authors that you are running at least Perl 5.000. Few authors now bother to “require 5.000” in their code, even though they probably should. If you have a Perl Version 4, you should consider an upgrade.
Most modules depend on other software not in a standard Perl distribution. These dependencies may be a particular Perl version, other CPAN modules, or C source code requiring compilation. These dependencies are listed with each entry.
Modules may also depend on other modules that are part of the standard Perl distribution, such as Carp.pm or Exporter.pm. Since these modules are distributed with Perl itself, it is assumed that they will be present. If you are using a nonstandard Perl distribution, you may generate errors when installing or using these modules. In that case, you will need to acquire the standard modules needed by the modules you are trying to use.
Synopsis
A synopsis of each module’s constructors and public methods is given. The format used begs some discussion.
The synopses are given in an object-oriented form not unlike javadoc. The following rules apply:
The first word of an entry indicates the object type returned by the constructor or method. Since Perl does not have strong typing, the value shown is an object if an object is returned, or a representation of the intent if a variable is returned. That is, a method may be listed as returning a boolean, but there is no boolean type in Perl. The actual value returned will be a number: 0 or undef for false, and a nonzero defined value for true. Therefore, a returned type of boolean allows you to test the result with an existence check on the variable.
If a method is abstract, meaning that it is to be implemented by subclasses, the word “abstract” will appear before the return type in the entry.
Deprecated and private methods are not shown.
When a method returns no useful information, it is said to return null although the actual return value may not be undef.
The listed arguments to constructors never show the implicit object reference.
The listed arguments to methods always show the implicit object self-reference. When calling these methods with the
objectRef->methodnotation, the object name does not need to be passed explicitly.