Perl Module Reference, Volume 1: Chapter 2Perl Core ModulesThis section documents the core Perl modules, many of which are included as part of the Perl distribution. This section also includes documentation of the pod modules, which describe Perl's internal document format.
Alias
Synopsis
use Alias qw(alias const attr);
alias TEN => $ten, Ten => \$ten, Ten => \&ten,
Ten => \@ten, Ten => \%ten, TeN => \*ten;
{
local @Ten;
my $ten = [1..10];
alias Ten => $ten; # local @Ten
}
const pi => 3.14, ten => 10;
package Foo;
use Alias;
sub new { bless {foo => 1, _bar => [2, 3]}, $_[0] }
sub a_method {
my $s = attr shift;
# $foo, @_bar are now local aliases for
# $_[0]{foo}, @{$_[0]{_bar}} etc.
}
sub b_method {
local $Alias::KeyFilter = "_";
local $Alias::AttrPrefix = "main::";
my $s = attr shift;
# local @::_bar is now available, ($foo, $::foo are not)
}
sub c_method {
local $Alias::KeyFilter = sub { $_ = shift; return (/^_/ ? 1 : 0) };
local $Alias::AttrPrefix = sub {
$_ = shift;
s/^_(.+)$/main::$1/;
return $_
};
my $s = attr shift;
# local @::bar is now available, ($foo, $::foo are not)
}
DescriptionThis module provides general mechanisms for aliasing Perl data for convenient access.
It works by putting values on the symbol table with user-supplied
names. Values that are references will get dereferenced to their base
types. This means that a value of
The exception to this rule is the default behavior of the
Functions
alias %{$_[0]}
but, in addition, also localizes the aliases, and does not dereference objects. Dereferencing of objects can be forced by setting the Deref option. See $Alias::Deref.
Configuration VariablesThe following configuration variables can be used to control the behavior of theattr function. They are typically set after the use Alias; statement. Another typical usage is to localize them in a block so that their values are effective only within that block.
Exportsalias attr ExamplesRun these code snippets and observe the results to become more familiar with the features of this module.
use Alias qw(alias const attr);
$ten = 10;
alias TEN => $ten, Ten => \$ten, Ten => \&ten,
Ten => \@ten, Ten => \%ten;
alias TeN => \*ten; # same as *TeN = *ten
# aliasing basic types
$ten = 20;
print "$TEN|$Ten|$ten\n"; # should print "20|20|20"
sub ten { print "10\n"; }
@ten = (1..10);
%ten = (a..j);
&Ten; # should print "10"
print @Ten, "|", %Ten, "\n";
# this will fail at run time
const _TEN_ => 10;
eval { $_TEN_ = 20 };
print $@ if $@;
# dynamically scoped aliases
@DYNAMIC = qw(m n o);
{
my $tmp = [ qw(a b c d) ];
local @DYNAMIC;
alias DYNAMIC => $tmp, PERM => $tmp;
$DYNAMIC[2] = 'zzz';
# prints "abzzzd|abzzzd|abzzzd"
print @$tmp, "|", @DYNAMIC, "|", @PERM, "\n";
@DYNAMIC = qw(p q r);
# prints "pqr|pqr|pqr"
print @$tmp, "|", @DYNAMIC, "|", @PERM, "\n";
}
# prints "mno|pqr"
print @DYNAMIC, "|", @PERM, "\n";
# named closures
my($lex) = 'abcd';
$closure = sub { print $lex, "\n" };
alias NAMEDCLOSURE => \&$closure;
NAMEDCLOSURE(); # prints "abcd"
$lex = 'pqrs';
NAMEDCLOSURE(); # prints "pqrs"
# hash/object attributes
package Foo;
use Alias;
sub new {
bless
{ foo => 1,
bar => [2,3],
buz => { a => 4},
privmeth => sub { "private" },
easymeth => sub { die "to recurse or to die, is the question" },
}, $_[0];
}
sub easymeth {
my $s = attr shift; # localizes $foo, @bar, %buz etc with values
eval { $s->easymeth }; # should fail
print $@ if $@;
# prints "1|2|3|a|4|private|"
print join '|', $foo, @bar, %buz, $s->privmeth, "\n";
}
$foo = 6;
@bar = (7,8);
%buz = (b => 9);
Foo->new->easymeth; # this will not recurse endlessly
# prints "6|7|8|b|9|"
print join '|', $foo, @bar, %buz, "\n";
# this should fail at run-time
eval { Foo->new->privmeth };
print $@ if $@;
NotesIt is worth repeating that the aliases created byalias and const will be created in the caller's namespace (although we can use the AttrPrefix option to specify a different namespace for attr). If that namespace happens to be localized, the aliases created will be local to that block. attr localizes the aliases for us. Remember that references will be available as their dereferenced types.
Aliases cannot be lexical, since, by neccessity, they live on the symbol table. However, lexicals can be aliased. Note that this provides a means of reversing the action of anonymous type generators
Any occurrence of Remember that aliases are very much like references, only we don't have to dereference them as often (which means we won't have to pound on the dollar signs so much). Using this module will dramatically reduce noise characters in object-oriented Perl code. We can dynamically make subroutines and named closures with this scheme. It is also possible to alias packages, but that might be construed as abuse.
Bugsuse strict 'vars'; is not very usable, since we depend so much on the symbol table. You can declare the attributes with use vars to avoid warnings. Setting $Alias::AttrPrefix to main:: is one way to avoid use vars and frustration. Tied variables cannot as of yet be aliased properly.
AuthorGurusamy Sarathy, gsar@umich.edu
CopyrightCopyright © 1995-97 Gurusamy Sarathy. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
See Alsoperl(1)
AutoLoader
Synopsispackage GoodStuff; use Exporter; use AutoLoader; @ISA = qw(Exporter AutoLoader); DescriptionThe AutoLoader module provides a standard mechanism for delayed loading of functions stored in separate files on disk. Each file has the same name as the function (plus a .al), and comes from a directory named after the package (with the auto directory). For example, the function namedGoodStuff::whatever() would be loaded from the file auto/GoodStuff/whatever.al. A module using the AutoLoader should have the special marker __END__ prior to the actual subroutine declarations. All code before this marker is loaded and compiled when the module is used. At the marker, Perl stops parsing the file. When a subroutine not yet in memory is called, the AUTOLOAD function attempts to locate it in a directory relative to the location of the module file itself. As an example, assume POSIX.pm is located in /usr/local/lib/perl5/POSIX.pm. The AutoLoader will look for the corresponding subroutines for this package in /usr/ local/lib/perl5/auto/POSIX/*.al.
Lexicals declared with The AutoLoader is a counterpart to the SelfLoader module. Both delay the loading of subroutines, but the SelfLoader accomplishes this by storing the subroutines right there in the module file rather than in separate files elsewhere. While this avoids the use of a hierarchy of disk files and the associated I/O for each routine loaded, the SelfLoader suffers a disadvantage in the one-time parsing of the lines after __DATA__, after which routines are cached. The SelfLoader can also handle multiple packages in a file. AutoLoader, on the other hand, reads code only as it is requested, and in many cases should be faster. But it requires a mechanism like AutoSplit to create the individual files. On systems with restrictions on filename length, the file corresponding to a subroutine may have a shorter name than the routine itself. This can lead to conflicting filenames. The AutoSplit module will warn of these potential conflicts when used to split a module.
AuthorPerl5 Porters, perl5-porters@perl.org
Carp
Synopsisuse Carp; carp "Be careful!"; # warn of errors (from perspective of caller) croak "We're outta here!"; # die of errors (from perspective of caller) confess "Bye!"; # die of errors with stack backtrace Descriptioncarp() and croak() behave like warn and die, respectively, except that they report the error as occurring not at the line of code where they are invoked, but at a line in one of the calling routines. Suppose, for example, that you have a routine goo() containing an invocation of carp(). In that caseand assuming that the current stack shows no callers from a package other than the current onecarp() will report the error as occurring where goo() was called. If, on the other hand, callers from different packages are found on the stack, then the error is reported as occurring in the package immediately preceding the package in which the carp() invocation occurs. The intent is to let library modules act a little more like built-in functions, which always report errors where you call them from.
AuthorPerl5 Porters, perl5-porters@perl.org
Config
Synopsis
use Config;
if ($Config{cc} =~ /gcc/) {
print "built by gcc
}
use Config qw(myconfig config_sh config_vars);
print myconfig();
print config_sh();
config_vars(qw(osname archname));
DescriptionThe Config module contains all the information that the Configure script had to figure out at Perl build time (over 450 values).[1]
Shell variables from the config.sh file (written by Configure) are stored in a read-only hash,
config_sh
config_vars(@names)
name='value';Names that are unknown are output as name='UNKNOWN';.
Here's a more sophisticated example using
use Config;
defined $Config{sig_name} or die "No sigs?";
foreach $name (split(' ', $Config{sig_name})) {
$signo{$name} = $i;
$signame[$i] = $name;
$i++;
}
print "signal #17 = $signame[17]
if ($signo{ALRM}) {
print "SIGALRM is $signo{ALRM}
}
Because configuration information is not stored within the Perl executable itself, it is possible (but unlikely) that the information might not relate to the actual Perl binary that is being used to access it. The Config module checks the Perl version number when loaded to try to prevent gross mismatches, but can't detect subsequent rebuilds of the same version.
AuthorPerl5 Porters, perl5-porters@perl.org
constant
Synopsis
use constant BUFFER_SIZE => 4096;
use constant ONE_YEAR => 365.2425 * 24 * 60 * 60;
use constant PI => 4 * atan2 1, 1;
use constant DEBUGGING => 0;
use constant ORACLE => 'oracle@cs.indiana.edu';
use constant USERNAME => scalar getpwuid($<);
use constant USERINFO => getpwuid($<);
sub deg2rad { PI * $_[0] / 180 }
print "This line does nothing" unless DEBUGGING;
DescriptionThis will declare a symbol to be a constant with the given scalar or list value.
When you declare a constant such as pi using the method shown above, each machine your program runs upon can have as many digits of accuracy as it can use. Also, your program will be easier to read and more likely to be maintained, and maintained correctly (and far less likely to send a space probe to the wrong planet because nobody noticed the one equation in which you wrote
NotesThe value or values are evaluated in a list context. You may override this withscalar, as shown previously. These constants do not directly interpolate into double-quoted strings, although you may use references to do so. See the perlref manpage for details about how this works.
print "The value of PI is ${\( PI )}.\n"; # scalar
print "Your USERINFO is @{[ USERINFO ]}.\n"; # list
Multiple values are returned as lists, not as arrays.
$homedir = USERINFO[7]; # WRONG $homedir = (USERINFO)[7]; # Right @homedir = USERINFO; # Get the whole listThe use of all caps for constant names is merely a convention, although it is recommended in order to make constants stand out, and to help avoid collisions with other barewords, keywords, and subroutine names. Constant names must begin with a letter. Symbols are package-scoped. That is, you can refer to a constant CONST in package Other as Other::CONST.
Omitting the value for a symbol gives it the value of
use constant UNICORNS => (); use constant LOGFILE => undef;The result from evaluating a list constant in a scalar context is not documented, and is not guaranteed to be any particular value in the future. In particular, you should not rely upon it being the number of elements in the list, especially since it is not that value in the current implementation.
Technical NoteIn the current implementation, scalar constants are actually inlinable subroutines. As of version 5.004 of Perl, the appropriate scalar constant is inserted directly in place of some subroutine calls, thereby saving the overhead of a subroutine call. See "Constant Functions" for details about how and when this happens.
BugsIn the current version of Perl, list constants are not inlined, some symbols may be redefined without generating a warning, anddefined works reliably only upon scalar constants. Also, in the current implementation, scalar constants and elements of list constants must be either undef, numbers, or strings. References are stringified, so they aren't especially useful. Magical values (such as $!) are also stringified, so they lose their magic. It is not possible to have a subroutine or keyword with the same name as a constant. (This is probably a good thing.) Unlike constants in some other languages, these Perl constants cannot be overridden on the command line or via environment variables.
AuthorTom Phoenix, rootbeer@teleport.com
CopyrightCopyright © 1997 Tom PhoenixThis module is free software; you can redistribute it or modify it under the same terms as Perl itself.
DynaLoader
Synopsispackage YourModule; require DynaLoader; @ISA = qw(... DynaLoader ...); bootstrap YourModule; DescriptionThis module defines the standard Perl interface to the dynamic linking mechanisms available on many platforms. A common theme throughout the module system is that using a module should be easy, even if the module itself (or the installation of the module) is more complicated as a result. This applies particularly to the DynaLoader. To use it in your own module, all you need are the incantations listed above in the synopsis. This will work whether YourModule is statically or dynamically linked into Perl. (This is a Configure option for each module.) Thebootstrap() method will either call YourModule's bootstrap routine directly if YourModule is statically linked into Perl, or if not, YourModule will inherit the bootstrap() method from DynaLoader, which will do everything necessary to load in your module, and then call YourModule's bootstrap() method for you, as if it were there all the time and you called it yourself. Piece of cake, of the have-it-and-eat-it-too variety.The rest of this description talks about the DynaLoader from the viewpoint of someone who wants to extend the DynaLoader module to a new architecture. The Configure process selects which kind of dynamic loading to use by choosing to link in one of several C implementations, which must be linked into Perl statically. (This is unlike other C extensions, which provide a single implementation that may be linked in either statically or dynamically.) The DynaLoader is designed to be a very simple, high-level interface that is sufficiently general to cover the requirements of SunOS, HP-UX, NeXT, Linux, VMS, Win-32, and other platforms. By itself, though, DynaLoader is practically useless for accessing non-Perl libraries because it provides almost no Perl-to-C "glue". There is, for example, no mechanism for calling a C library function or supplying its arguments in any sort of portable form. This job is delegated to the other extension modules that you may load in by using DynaLoader.
Internal Interface Summary
@dl_library_path @dl_resolve_using @dl_require_symbols $dl_debug
bootstrap($modulename); @filepaths = dl_findfile(@names); $filepath = dl_expandspec($spec); $libref = dl_load_file($filename); $symref = dl_find_symbol($libref, $symbol); @symbols = dl_undef_symbols(); dl_install_xsub($name, $symref [, $filename]); $message = dl_error;The bootstrap() and dl_findfile() routines are standard across all platforms, and so are defined in DynaLoader.pm. The rest of the functions are supplied by the particular .xs file that supplies the implementation for the platform. (You can examine the existing implementations in the ext/DynaLoader/*.xs files in the Perl source directory. You should also read DynaLoader.pm, of course.) These implementations may also tweak the default values of the variables listed below.
Variables
@dl_resolve_using = dl_findfile('-lsocket');
Note that, similar to errno in UNIX, a successful function call does not reset this message. Implementations should detect the error as soon as it occurs in any of the other functions and save the corresponding message for later retrieval. This will avoid problems on some platforms (such as SunOS) where the error message is very temporary (see, for example, dlerror(3)).
Names can be specified in a variety of platform-independent forms. Any names in the form -lname are converted into libname.*, where .* is an appropriate suffix for the platform. If a name does not already have a suitable prefix or suffix, then the corresponding file will be sought by trying prefix and suffix combinations appropriate to the platform: $name.o, lib$name.* and $name. If any directories are included in @names, they are searched before @dl_library_path. Directories may be specified as -Ldir. Any other names are treated as filenames to be searched for. Using arguments of the form -Ldir and -lname is recommended. Example:
@dl_resolve_using = dl_findfile(qw(-L/usr/5lib -lposix));
$filepath = dl_expandspec($spec)
$libref = dl_load_file($filename) dl_load_file() returns the undefined value on error. (On systems that provide a handle for the loaded object such as SunOS and HP-UX, the returned handle will be $libref. On other systems $libref will typically be $filename or a pointer to a buffer containing $filename. The application should not examine or alter $libref in any way.) Below are some of the functions that do the real work. Such functions should use the current values of @dl_require_symbols and @dl_resolve_using if required.
SunOS: dlopen($filename)
HP-UX: shl_load($filename)
Linux: dld_create_reference(@dl_require_symbols);
dld_link($filename)
NeXT: rld_load($filename, @dl_resolve_using)
VMS: lib$find_image_symbol($filename,
$dl_require_symbols[0])
$symref = dl_find_symbol($libref, $symbol)If the target system has separate functions to search for symbols of different types, then dl_find_symbol() should search for function symbols first and then search for other types. The exact manner in which the address is returned in $symref is not currently defined. The only initial requirement is that $symref can be passed to, and understood by, dl_install_xsub(). Here are some current implementations:
SunOS: dlsym($libref, $symbol)
HP-UX: shl_findsym($libref, $symbol)
Linux: dld_get_func($symbol) and/or dld_get_symbol($symbol)
NeXT: rld_lookup("_$symbol")
VMS: lib$find_image_symbol($libref, $symbol)
@symbols = dl_undef_symbols()It returns () if these names are not known. Don't worry if your platform does not provide a mechanism for this. Most platforms do not need it and hence do not provide it; they just return an empty list.
dl_install_xsub($perl_name, $symref [, $filename])This is simply a direct call to newXSUB(). It returns a reference to the installed function. The $filename parameter is used by Perl to identify the source file for the function if required by die, caller, or the debugger. If $filename is not defined, then DynaLoader will be used.
bootstrap($module);It performs the following actions:
AuthorPerl5 Porters, perl5-porters@perl.org
English
Synopsis
use English;
...
if ($ERRNO =~ /denied/) { ... }
DescriptionThis module provides aliases for the built-in "punctuation" variables. Variables with side effects that get triggered merely by accessing them (like $0) will still have the same effects under the aliases.
For those variables that have an awk(1) version, both long and short English alternatives are provided. For example, the Here is the list of variables along with their English alternatives:
AuthorPerl5 Porters, perl5-porters@perl.org
Exporter
Synopsis# in module YourModule.pm: package YourModule; use Exporter (); @ISA = qw(Exporter); @EXPORT = qw(...); # Symbols to export by default. @EXPORT_OK = qw(...); # Symbols to export on request. %EXPORT_TAGS = (tag => [...]); # Define names for sets of symbols. # in other files that wish to use YourModule: use YourModule; # Import default symbols into my package. use YourModule qw(...); # Import listed symbols into my package. use YourModule (); # Do not import any symbols! DescriptionAny module may define a class method calledimport(). Perl automatically calls a module's import() method when processing the use statement for the module. The module itself doesn't have to define the import() method, though. The Exporter module implements a default import() method that many modules choose to inherit instead. The Exporter module supplies the customary import semantics, and any other import() methods will tend to deviate from the normal import semantics in various (hopefully documented) ways. Now we'll talk about the normal import semantics.
Specialized Import ListsIgnoring the class name, which is always the first argument to a class method, the arguments that are passed into theimport() method are known as an import list. Usually the import list is nothing more than a list of subroutine or variable names, but occasionally you may want to get fancy. If the first entry in an import list begins with !, :, or /, the list is treated as a series of specifications that either add to or delete from the list of names to import. They are processed left to right. Specifications are in the form:
A leading For example, suppose that YourModule.pm says:
@EXPORT = qw(A1 A2 A3 A4 A5);
@EXPORT_OK = qw(B1 B2 B3 B4 B5);
%EXPORT_TAGS = (
T1 => [qw(A1 A2 B1 B2)],
T2 => [qw(A1 A2 B3 B4)]
);
Individual names in EXPORT_TAGS must also appear in @EXPORT or @EXPORT_OK. Note that you cannot use the tags directly within either @EXPORT or @EXPORT_OK (though you could preprocess tags into either of those arrays, and in fact, the export_tags() and export_ok_tags() functions below do precisely that).An application using YourModule can then say something like this:
use YourModule qw(:DEFAULT :T2 !B3 A3);The :DEFAULT adds in A1, A2, A3, A4, and A5. The :T2 adds in only B3 and B4, since A1 and A2 were already added. The !B3 then deletes B3, and the A3 does nothing because A3 was already included. Other examples include:
use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET); use POSIX qw(:errno_h :termios_h !TCSADRAIN !/^EXIT/);Remember that most patterns (using //) will need to be anchored with a leading ^, for example, /^EXIT/ rather than /EXIT/.You can say:
BEGIN { $Exporter::Verbose=1 }
in order to see how the specifications are being processed and what is actually being imported into modules.
Module Version CheckingThe Exporter module will convert an attempt to import a number from a module into a call to$module_name->require_version($value). This can be used to validate that the version of the module being used is greater than or equal to the required version. The Exporter module also supplies a default require_version() method, which checks the value of $VERSION in the exporting module.
Since the default Prior to release 5.004 or so of Perl, this worked only with modules that use the Exporter module; in particular, this means that you can't check the version of a class module that doesn't require the Exporter module.
Managing Unknown SymbolsIn some situations you may want to prevent certain symbols from being exported. Typically this applies to extensions with functions or constants that may not exist on some systems.The names of any symbols that cannot be exported should be listed in the @EXPORT_FAIL array.
If a module attempts to import any of these symbols, the Exporter will give the module an opportunity to handle the situation before generating an error. The Exporter will call an
@failed_symbols = $module_name->export_fail(@failed_symbols);If the export_fail() method returns an empty list, then no error is recorded and all requested symbols are exported. If the returned list is not empty, then an error is generated for each symbol and the export fails. The Exporter provides a default export_fail() method that simply returns the list unchanged.
Uses for the
Tag Handling Utility FunctionsSince the symbols listed within %EXPORT_TAGS must also appear in either @EXPORT or @EXPORT_OK, two utility functions are provided that allow you to easily add tagged sets of symbols to @EXPORT or @EXPORT_OK:
%EXPORT_TAGS = (Bactrian => [qw(aa bb cc)],
Dromedary => [qw(aa cc dd)]);
Exporter::export_tags('Bactrian'); # add aa bb cc to @EXPORT
Exporter::export_ok_tags('Dromedary'); # add aa cc dd to @EXPORT_OK
Any names that are not tags are added to @EXPORT or @EXPORT_OK unchanged, but will trigger a warning (with Ðw) to avoid misspelled tag names being silently added to @EXPORT or @EXPORT_OK. Future versions may regard this as a fatal error.
AuthorPerl5 Porters, perl5-porters@perl.org
Filter::cpp
Synopsisuse Filter::cpp; DescriptionThis source filter pipes the current source file through the C preprocessor (cpp) if it is available. As with all source filters, its scope is limited to the current source file only. Every file you want to be processed by the filter must have the line:
use Filter::cpp ;near the top. Here is an example script that uses the filter:
use Filter::cpp ; #define FRED 1 $a = 2 + FRED ; print "a = $a\n" ; #ifdef FRED print "Hello FRED\n" ; #else print "Where is FRED\n" ; #endifThis is what it will output:
a = 3 Hello FRED AuthorPaul Marquess, pmarquess@bfsec.bt.co.uk
Filter::decrypt
Synopsisuse Filter::decrypt; DescriptionThis is a sample decrypting source filter.Although this is a fully functional source filter, which does implement a very simple decrypt algorithm, it is not intended to be used as it is supplied. Consider it as a template which you can combine with a proper decryption algorithm to develop your own decryption filter.
WarningIt is important to note that a decryption filter can never provide complete security against attack. At some point the parser within Perl needs to be able to scan the original decrypted source. This means that at some stage, fragments of the source will exist in a memory buffer.The best you can hope to achieve by decrypting your Perl source using a source filter is to make it impractical to crack. Given that proviso, there are a number of things you can do to make life more difficult for the prospective cracker.
unexec/undump method. See the Perl FAQ for further details.
AuthorPaul Marquess, pmarquess@bfsec.bt.co.uk
Filter::exec
Synopsisuse Filter::exec qw(command parameters) ; DescriptionThis filter pipes the current source file through the program that corresponds to the given command (with possible parameters).As with all source filters, its scope is limited to the current source file only. Every file you want to be processed by the filter must have the line:
use Filter::exec qw(command) ;near the top. Here is an example script which uses the filter:
use Filter::exec qw(tr XYZ PQR) ; $a = 1 ; print "XYZ a = $a\n" ;This is the output:
PQR = 1 WarningYou should be very careful when using this filter. Because of the way the filter is implemented it is possible to end up with deadlock. Be especially careful when stacking multiple instances of the filter in a single source file.
AuthorPaul Marquess, pmarquess@bfsec.bt.co.uk
Filter::sh
Synopsisuse Filter::sh 'command' ; DescriptionThis filter pipes the current source file through the program that corresponds to the command parameter using the Bourne shell.As with all source filters, its scope is limited to the current source file only. Every file you want to be processed by the filter must have this line near the top:
use Filter::sh 'command' ;Here is an example script that uses the filter:
use Filter::sh 'tr XYZ PQR' ; $a = 1 ; print "XYZ a = $a\n" ;This is what it will output:
PQR = 1 WarningYou should be very careful when using this filter. Because of the way the filter is implemented it is possible to end up with deadlock. Be especially careful when stacking multiple instances of the filter in a single source file.
AuthorPaul Marquess, pmarquess@bfsec.bt.co.uk
Filter::tee
Synopsisuse Filter::tee 'filename' ; use Filter::tee '>filename' ; use Filter::tee '>>filename' ; DescriptionThis filter copies all text from the line after theuse in the current source file to the file specified by the parameter filename.
By default (and when the filename is prefixed with a
If the output filename is prefixed with This filter is useful as a debugging aid when developing other source filters.
AuthorPaul Marquess, pmarquess@bfsec.bt.co.uk
Filter::Util::Call
SynopsisMethod filter:
package MyFilter ;
use Filter::Util::Call ;
sub import
{
my($type, @arguments) = @_ ;
filter_add([]) ;
}
sub filter
{
my($self) = @_ ;
my($status) ;
$status = filter_read() ;
$status ;
}
1 ;
Closure filter:
package MyFilter ;
use Filter::Util::Call ;
sub import
{
my($type, @arguments) = @_ ;
filter_add(
sub
{
my($status) ;
$status = filter_read() ;
$status ;
} )
}
1 ;
DescriptionThis module provides you with the framework to write source filters in Perl.A Perl source filter is implemented as a Perl module. The structure of the module can take one of two broadly similar formats (as shown previously in the Synopsis). To distinguish between them, the first will be referred to as a method filter and the second as a closure filter. To make use of either of the two filter modules, place the line shown here in a Perl source file:
use MyFilter;The skeleton modules shown above are fully functional source filters, albeit fairly useless ones. As they stand, all they do is pass the source stream through, without modifying it at all.
As you can see, both modules have a broadly similar structure. They both make use of the Filter::Util::Call module and both have an To make proper use of the closure filter shown above you need to have a good understanding of the concept of a closure. See the perlref manpage for more details on the mechanics of closures.
MethodsThe following methods are included in Filter::Util::Call:
use MyFilter qw(a b c);will result in the @_ array having the following values:
@_ [0] => "MyFilter" @_ [1] => "a" @_ [2] => "b" @_ [3] => "c"Before terminating, the import function must explicitly install the filter by calling filter_add.
< 0 Error = 0 EOF > 0 OK
FunctionsFilter::Util::Call provides the following functions:
$status = filter_read() ; $status = filter_read($size) ;The first form is used to request a line, while the second requests a block.
ExportsThe following functions are exported byFilter::Util::Call:
filter_add() filter_read() filter_read_exact() filter_del() ExamplesHere are a few examples which simply illustrate the key concepts, as most of them (in their current form) are of little practical use.The examples subdirectory has copies of all these filters implemented both as method filters and as closure filters.
Example 1: A simple filterBelow is a method filter which is hard-wired to replace all occurrences of the stringJoe with Jim.
package Joe2Jim ;
use Filter::Util::Call ;
sub import
{
my($type) = @_ ;
filter_add(bless []) ;
}
sub filter
{
my($self) = @_ ;
my($status) ;
s/Joe/Jim/g
if ($status = filter_read()) > 0 ;
$status ;
}
1 ;
Here is an example of using the filter:
use Joe2Jim ; print "Where is Joe?\n" ;This is what the script above will print:
Where is Jim? Example 2: Using the contextTo make the previous example more usuable in real-world scenarios, we make use of the context data and allow arbitrary from and to strings to be used. This time we will use a closure filter. To reflect its enhanced role, the filter is calledSubst:
package Subst ;
use Filter::Util::Call ;
use Carp ;
sub import
{
croak("usage: use Subst qw(from to)")
unless @_ == 3 ;
my ($self, $from, $to) = @_ ;
filter_add(
sub
{
my ($status) ;
s/$from/$to/
if ($status = filter_read()) > 0 ;
$status ;
})
}
1 ;
and is used like this:
use Subst qw(Joe Jim) ; print "Where is Joe?\n" ; Example 3: Using the context within the filterHere is a filter that is a variation of theJoe2Jim filter. As well as substituting all occurrences of Joe to Jim, it keeps a count of the number of substitutions made in the context object.
Once EOF is detected (
package Count ;
use Filter::Util::Call ;
sub filter
{
my ($self) = @_ ;
my ($status) ;
if (($status = filter_read()) > 0 ) {
s/Joe/Jim/g ;
++ $$self ;
}
elsif ($$self >= 0) { # EOF
$_ = "print q[Made ${$self} substitutions\n]" ;
$status = 1 ;
$$self = -1 ;
}
$status ;
}
sub import
{
my ($self) = @_ ;
my ($count) = 0 ;
filter_add(\$count) ;
}
1 ;
Here is a script which uses this filter:
use Count ; print "Hello Joe\n" ; print "Where is Joe\n" ;It outputs:
Hello Jim Where is Jim Made 2 substitutions Example 4: Using filter_delAnother variation on a theme, this filter modifies theSubst filter to allow a starting and stopping pattern to be specified as well as the from and to patterns. If you know the vi editor, it is equivalent to this command:
:/start/,/stop/s/from/to/When used as a filter we want to invoke it like this:
use NewSubst qw(start stop from to) ;Here is the module:
package NewSubst ;
use Filter::Util::Call ;
use Carp ;
sub import
{
my ($self, $start, $stop, $from, $to) = @_ ;
my ($found) = 0 ;
croak("usage: use Subst qw(start stop from to)")
unless @_ == 5 ;
filter_add(
sub
{
my ($status) ;
if (($status = filter_read()) > 0) {
$found = 1
if $found == 0 and /$start/ ;
if ($found) {
s/$from/$to/ ;
filter_del() if /$stop/ ;
}
}
$status ;
} )
}
1 ;
AuthorPaul Marquess, pmarquess@bfsec.bt.co.uk
Filter::Util::Exec
DescriptionThis module is provides the interface to allow the creation of source filters that use a UNIX coprocess.See Filter::exec, Filter::cpp and Filter::sh for examples of the use of this module.
AuthorPaul Marquess, pmarquess@bfsec.bt.co.uk
perlpod
DescriptionA pod-to-whatever translator reads a pod file paragraph by paragraph and translates it to the appropriate output format. There are three kinds of paragraphs:
=head1 heading =head2 heading =item text =over N =back =cut =pod =for X =begin X =end XThe =pod directive does nothing beyond telling the compiler to lay off parsing code through the next =cut. It's useful for adding another paragraph to the doc if you're mixing up code and pod a lot.
=for html <br> <p> This is a raw HTML paragraph </p>The paired commands =begin and =end work very similarly to =for, but instead of only accepting a single paragraph, all text from =begin to a paragraph with a matching =end are treated as a particular format. Here are some examples of how to use these:
=begin html <br>Figure 1.<IMG SRC="figure1.png"><br> =end html =begin text --------------- | foo | | bar | --------------- ^^^^ Figure 1. ^^^^ =end textSome format names that formatters currently are known to accept include roff, man, latex, tex, text, and html. (Some formatters treat some of these as synonyms.) And don't forget, when using any command, that the command lasts until the end of the paragraph, not the line. Hence in the examples below, you can see the empty line after each command to end its paragraph. Some examples of lists include:
=over 4 =item * First item =item * Second item =back =over 4 =item Foo() Description of Foo function =item Bar() Description of Bar function =back
I<text> Italicize text, used for emphasis or variables
B<text> Embolden text, used for switches and programs
S<text> Text contains non-breaking spaces
C<code> Literal code
L<name> A link (cross-reference) to name
L<name> Manual page
L<name/ident> Item in manual page
L<name/"sec"> Section in other manual page
L<"sec"> Section in this manual page
(the quotes are optional)
L</"sec"> Ditto
F<file> A filename
X<index> An index entry
Z<> A zero-width character
E<escape> A named character (very similar to HTML escapes)
E<lt> A literal <
E<gt> A literal >
(These are optional, except in other interior
sequences and when preceded by a capital letter)
E<n> Character number n (probably ASCII)
E<html> Some non-numeric HTML entity, such
as E<Agrave>
That's it. The intent is simplicity, not power. I wanted paragraphs to look like paragraphs (block format), so that they stand out visually, and so that I could run them through fmt easily to reformat them (that's F7 in my version of vi). I wanted the translator (and not me) to worry about whether " or ' is a left quote or a right quote within filled text, and I wanted it to leave the quotes alone, dammit, in verbatim mode, so I could slurp in a working program, shift it over four spaces, and have it print out, er, verbatim. And presumably in a constant-width font. In particular, you can leave things like this verbatim in your text:
Embedding Pods in Perl ModulesYou can embed pod documentation in your Perl scripts. Start your documentation with=head1 at the beginning and end it with =cut. Perl ignores the pod text. See any of the supplied library modules for examples. If you're going to put your pods at the end of the file, and you're using an __END__ or __DATA__ cut mark, make sure to put an empty line there before the first pod directive.
__END__ =head1 NAME modern - I am a modern moduleIf you had not had that empty line there, then the translators wouldn't have seen the pod.
Common Pod Pitfalls
AuthorLarry Wall
See Alsopod2man, PODs: Embedded Documentation
Pod::Text
Synopsis
use Pod::Text;
pod2text("perlfunc.pod");
or:
use Pod::Text;
package MyParser;
@ISA = qw(Pod::Text);
sub new {
## constructor code ...
}
## implementation of appropriate subclass methods ...
package main;
$parser = new MyParser;
@ARGV = ('-') unless (@ARGV > 0);
for (@ARGV) {
$parser->parse_from_file($_);
}
DescriptionPod::Text is a module that can convert documentation in the pod format (such as can be found throughout the Perl distribution) into formatted ASCII. Termcap is optionally supported for boldface/underline and can be enabled via$Pod::Text::termcap=1. If termcap has not been enabled, then backspaces are used to simulate bold and underlined text.
A separate
The single function
AuthorTom Christiansen, tchrist@mox.perl.comModified to derive from Pod::Parser by Brad Appleton, Brad_Appleton-GBDA001@email.mot.com
See AlsoPod::Parser
pod2fm
Synopsis
pod2fm [-mmlonly |
-nodoc [-lock]
[-book [book_name] [-noopen]
[-template document [-format types]... [-toc] [-index]
]
]
DescriptionThis program parses all files a with .pod extension and creates FrameMaker documents. You can control what is generated by arguments given on the command line.pod2fm can:
Options
-format Page,Paragraph,CharacterYou can also have more than one -format option on the command line.
TemplatesBy using the-template command-line option when you are generating a book using the -book option, you can override the default formats that pod2fm produces.
A template is a FrameMaker document, in binary form or MIF, that has formats you want already applied to it. With this version of
Paragraph FormatsThere are several paragraph formats thatpod2fm uses, and there is a mapping from the pod command to the paragraph format that is produced. The exception to the mapping is the =over and =back commands: they modify the paragraph format by shifting its left edge by .1" times the amount in the =over command. You need to take this into account when you are changing the paragraph format. If you drop the size of the font in the format, you do not get a smaller shift. An =over 5 always gives an indent of .5".
The paragraph formats that
=head1 textwhere text is printed in this format. The =over and =back commands do not change this format.
=head2 textwhere text is printed in this format. The =over and =back commands do not change this format.
=item n[.]where n is any number followed by an optional period, the next paragraph is marked with this format and prints as a hanging indent that starts with an automatically generated number and a period. The start of the paragraph is shifted by the amount in the =over command. Any paragraphs that come after the first are marked with pod_Body and the left edge is shifted by the amount from the =over command.
=item *the next paragraph is marked with this format and prints as a hanging indent that starts with a bullet. The start of the paragraph is shifted by the amount in the =over command. Any paragraphs that come after the first are marked with pod_Body and the left edge is shifted by the amount from the =over command.
=item * textthe text is printed after a bullet, on a line by itself. Any paragraphs that come after the first are marked with pod_Body and the left edge is shifted by the amount from the =over command.
=item textthe text is printed as a hanging indent. The next paragraph is marked with this format and prints with the start of the paragraph shifted by the amount in the =over command. Any paragraphs that come after the first are marked with pod_Body and the left edge is shifted by the amount from the =over command.
____hang_______text
| |
+- spaces +- tabs
or
tabs
the hang is printed as a hanging indent and the text is printed with the left edge shifted to 2.5" from the current pod_Body left edge. The rest of the lines in the paragraph are treated the same, i.e., each line in the pod's paragraph is converted to a FrameMaker paragraph that is marked with pod_il. Any paragraphs that come after the first are marked with pod_Body and the left edge is shifted by the amount from the =over command.
____text
|
+- spaces
or
tabs
the text, including the leading whitespace, is printed with the left edge shifted to the current pod_Body left edge. The rest of the lines in the paragraph are treated the same, i.e., each line in the pod's paragraph is converted to a FrameMaker paragraph that is marked with pod_pre. Any paragraphs that come after the first are marked with pod_Body, and the left edge is shifted by the amount from the =over command.
Table of ContentsIf you are producing a book, and you have a-template command-line option, and you are importing the Master Page Layout (-format Page or the default), you can produce a Table of Contents by adding the -toc option. pod2fm automatically adds a generated document called book_nameTOC.doc to the book file, where book_name is the optional argument to the -book command-line option. If no argument is give on the -book, you get a document called perlTOC.doc. To specify the format of the Table of Contents, you need to go to the reference pages of the template document and create a flow called TOC. Within the flow, create a picture of what the Table of Contents will look like. You can add building blocks to the picture that allow you to control what is printed, e.g., the page number and text for the TOC entry. See the FrameMaker On-Line Help or Using FrameMaker printed manual for a complete description of how to set up a TOC Reference page.
The TOC entry is derived from paragraphs in the documents in the book that are marked with specific paragraph formats. To make a TOC entry show, you need to create a new paragraph format that tracks the format used in the documents. The new paragraph has the form:
format_nameTOCwhere format_name is the format name used in the document. Here is an example of a TOC specification:
Paragraph tagged Specifies ---------------- --------- pod_TITLE <$paratext><$nopage> pod_head1 <$paratext>\t<$pagenum> pod_head2 <$paratext>\t<$pagenum>which prints something like this:
POD2FM
NAME 1
SYNOPSIS 1
DESCRIPTION 1
OPTIONS 1
TEMPLATES 3
Paragraph Formats 3
Table of Contents 5
Index 6
BUGS 6
AUTHORS 7
IndexAn Index document is much the same as a Table of Contents document: you must be generating a book and importing Reference Page Layouts from a template, and have a-index command-line option. The format for the Index is also specified on a Reference Page in a flow called IX, and it has its own set of building blocks. Please see the FrameMaker documentation for more details on how to create the Index Reference Page.
Bugsfmbatch dies when it tries to work on a Table of Contents or an Index. This happens both in ImportFormats and Update. To get around this, just open the book file in maker and do the Import Formats and Update there. You can't change the amount of indent using a template file (yet...).
AuthorsBased onpod2html. Extended by Mark Pease, Mark_Pease-RXYE0@email.mot.com, for MML. fmbatch and book support added by Tim Bunce, Tim.Bunce@ig.co.uk. Please send bug reports to Mark Pease.
SelfLoader
Synopsis
package GoodStuff;
use SelfLoader;
[initializing code]
__DATA__
sub {...};
DescriptionThis module is used for delayed loading of Perl functions that (unlike AutoLoader functions) are packaged within your script file. This gives the appearance of faster loading.In the example above, SelfLoader tells its user (GoodStuff) that functions in the GoodStuff package are to be autoloaded from after the __DATA__ token. The __DATA__ token tells Perl that the code for compilation is finished. Everything after the __DATA__ token is available for reading via the filehandle GoodStuff::DATA, where GoodStuff is the name of the current package when the __DATA__ token is reached. This token works just the same as __END__ does in the package main, except that the data after __END__ is retrievable only in package main, whereas data after __DATA__ is retrievable in whatever the current package is. Note that it is possible to have __DATA__ tokens in the same package in multiple files, and that the last __DATA__ token in a given package that is encountered by the compiler is the one accessible by the filehandle. That is, whenever the __DATA__ token is parsed, any DATA filehandle previously open in the current package (opened in a different file, presumably) is closed so that the new one can be opened. (This also applies to __END__ and the main::DATA filehandle: main::DATA is reopened whenever __END__ is encountered, so any former association is lost.)
SelfLoader AutoloadingThe SelfLoader will read from the GoodStuff::DATA filehandle to get definitions for functions placed after __DATA__, and then evaluate the requested subroutine the first time it's called. The costs are the one-time parsing of the data after __DATA__, and a load delay for the first call of any autoloaded function. The benefits are a speeded up compilation phase, with no need to load functions that are never used.You can use __END__ after __DATA__. The SelfLoader will stop reading from DATA if it encounters the __END__ token, just as you might expect. If the __END__ token is present, and is followed by the token DATA, then the SelfLoader leaves the GoodStuff::DATA filehandle open on the line after that token. The SelfLoader exports the AUTOLOAD subroutine to the package using the SelfLoader, and this triggers the automatic loading of an undefined subroutine out of its DATA portion the first time that subroutine is called. There is no advantage to putting subroutines that will always be called after the __DATA__ token.
Autoloading and File-Scoped LexicalsAmy $pack_lexical statement makes the variable $pack_lexical visible only up to the __DATA__ token. That means that subroutines declared elsewhere cannot see lexical variables. Specifically, autoloaded functions cannot see such lexicals (this applies to both the SelfLoader and the AutoLoader). The use vars pragma (see later in this chapter) provides a way to declare package-level globals that will be visible to autoloaded routines.
SelfLoader and AutoLoaderThe SelfLoader can replace the AutoLoader--just changeuse AutoLoader to use SelfLoader[2] and the __END__ token to __DATA__.There is no need to inherit from the SelfLoader. The SelfLoader works similarly to the AutoLoader, but picks up the subroutine definitions from after the __DATA__ instead of in the lib/auto/ directory. SelfLoader needs less maintenance at the time the module is installed, since there's no need to run AutoSplit. And it can run faster at load time because it doesn't need to keep opening and closing files to load subroutines. On the other hand, it can run slower because it needs to parse the code after the __DATA__. Details of the AutoLoader and another view of these distinctions can be found in that module's documentation.
How to Read DATA from Your Perl Program(This section is relevant only if you want to use the GoodStuff::DATA together with the SelfLoader.)The SelfLoader reads from wherever the current position of the GoodStuff::DATA filehandle is, until EOF or the __END__ token. This means that if you want to use that filehandle (and only if you want to), you should either
Classes and Inherited MethodsThis section is only relevant if your module is a class, and has methods that could be inherited.A subroutine stub (or forward declaration) looks like:
sub stub;That is, it is a subroutine declaration without the body of the subroutine. For modules that aren't classes, there is no real need for stubs as far as autoloading is concerned.
For modules that are classes, and need to handle inherited methods, stubs are needed to ensure that the method inheritance mechanism works properly. You can load the stubs into the module at require time, by adding the statement The alternative is to put the stubs in before the __DATA__ token before releasing the module, and for this purpose the Devel::SelfStubber module is available. However this does require the extra step of ensuring that the stubs are in the module. If you do this, we strongly recommended that you do it before releasing the module and not at install time.
Multiple Packages and Fully Qualified Subroutine NamesSubroutines in multiple packages within the same file are supported--but you should note that this requires exporting SelfLoader::AUTOLOAD to every package which requires it. This is done automatically by the SelfLoader when it first loads the subs into the cache, but you should really specify it in the initialization before __DATA__ by putting ause SelfLoader statement in each package.Fully qualified subroutine names are also supported. For example:
will all be loaded correctly by the SelfLoader, and the SelfLoader will ensure that the packages "foo" and "baz" correctly have the SelfLoader::AUTOLOAD method when the data after __DATA__ is first parsed.
AuthorJack Shirazi, js@biu.icnet.uk
CopyrightCopyright © 1995 Jack Shirazi. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
See AlsoAutoLoader
UNIVERSAL
Synopsisrequire UNIVERSAL; $class = $any_object->class(); $bool = $any_object->is_instance(); DescriptionUNIVERSAL provides general default methods that any object can call.
Methods
ExampleThe following illustrates the methods, and can be executed usingperl -x UNIVERSAL.pm:
#!perl
require UNIVERSAL;
package C;
sub new {bless []}
package main;
sub test {
my($obj,$meth,@args) = @_;
print $obj,'->',$meth,'(',@args,") gives '",
join(',',$obj->$meth(@args)),"'\n"
}
test(C,'is_instance'); #C->is_instance()
test(C->new(),'is_instance'); #C->new()->is_instance()
test(C,'class'); #C->class()
test(C->new(),'class'); #C->new()->class() "foo"
__END__
AuthorJack Shirazi, js@biu.icnet.uk
CopyrightCopyright © 1995 Jack Shirazi. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
[1] Perl was written in C, not because it's a portable language, but because it's a ubiquitous language. A bare C program is about as portable as Chuck Yeager on foot. |